Troubleshooting Guide

This guide covers the most common issues you may encounter when using Scitor, along with solutions to resolve them.

Emails not arriving as Issues/Discussions

If inbound emails aren’t being converted to GitHub Issues or Discussions, check the following:

1. Email forwarding configuration — Ensure your email provider is forwarding to the correct Scitor inbound address. Check your forwarding rules are active and not paused.

2. MX records — Verify your domain’s MX records point to parse.scitor.io. Use dig MX yourdomain.com or an online DNS checker to confirm.

3. Blocked sender — The sender may have been previously blocked. Use /unblock-sender on any issue to remove a sender from the block list.

4. Installation status — Confirm the Scitor GitHub App is still installed and has access to the target repository. Check your GitHub App installation settings.

5. Spam score — Emails with a high spam score may be automatically filtered. Check the sender’s email authentication (SPF, DKIM, DMARC).

/send command not working

If the /send command isn’t sending emails:

1. Metadata comment — Every inbound issue contains a hidden HTML comment with sender metadata. If this comment is edited or deleted, /send cannot determine the recipient. Do not modify the issue body’s hidden comment block.

2. Outbound email limit — Check whether you’ve exceeded your plan’s monthly outbound email limit (100 for Free, 500 for Pro). Use /report to check your current usage.

3. Email provider configuration — Verify that your email provider API key is configured. Scitor requires either RESEND_API_KEY or SENDGRID_API_KEY to send outbound emails.

4. Sender address — Ensure the configured sender address is valid and verified with your email provider.

AI triage not labeling tickets

If AI analysis labels (sentiment, category) aren’t being applied:

1. Plan check — AI triage is a Pro plan feature. Verify your plan is active with /plan.

2. Configuration — Ensure ai: true is set in your scitor.yaml configuration file.

3. Content type — AI analysis requires text content to process. Image-only emails or emails with very little text may not trigger analysis.

SLA deadlines seem wrong

If SLA response or resolution deadlines don’t match your expectations:

1. Business hours — Check your business hours configuration in scitor.yaml. SLA timers only count time during configured business hours.

2. Timezone — Verify the timezone setting in your SLA configuration matches your team’s working timezone.

3. Waiting on customer — SLA timers automatically pause when the waiting-on-customer label is applied to an issue. Remove the label to resume the timer.

4. Check SLA state — Use /sla status on any issue to see the current SLA state, including elapsed time and remaining time.

Knowledge base not updating

If your documentation site isn’t reflecting recent changes:

1. Docs folder path — Ensure the docs configuration in scitor.yaml points to the correct folder in your repository.

2. Branch — Only pushes to the default branch trigger a knowledge base rebuild. Changes on feature branches won’t be published until merged.

3. Build logs — Check for build errors that may prevent the docs from being published. Look for syntax errors in frontmatter or invalid Markdown.

4. R2 bucket permissions — Verify the R2 storage bucket has the correct permissions for Scitor to write the built documentation files.

CSAT surveys not sending

If customer satisfaction surveys aren’t being sent after issues are closed:

1. CSAT enabled — Verify CSAT surveys are enabled in your scitor.yaml configuration.

2. Timing — Surveys are sent after an issue is closed, with a configurable delay. The survey won’t send immediately upon closing.

3. Cron schedule — The CSAT survey job runs on a cron schedule every 5 minutes. There may be a short delay before the survey is dispatched.

4. Duplicate prevention — Only one survey is sent per issue. If a survey has already been sent for a given issue, it won’t be sent again.

Custom domain not working

If your custom docs domain isn’t resolving or showing your knowledge base:

1. DNS records — Verify that the required DNS records (CNAME or A record) are correctly configured with your DNS provider.

2. Domain verification — Use /verify-domain to check the current verification status of your domain.

3. DNS propagation — Allow up to 48 hours for DNS changes to propagate globally. Use an online DNS propagation checker to monitor progress.

4. Domain authentication — Ensure the domain has been authenticated via /authenticate-domain for email sending purposes.

Form submissions not creating tickets

If web form submissions aren’t being converted to GitHub Issues:

1. Form ID — Check that the form ID used in the embed code is valid and the form is active.

2. Turnstile CAPTCHA — If CAPTCHA verification is enabled for the form, ensure the Cloudflare Turnstile site key is correctly configured.

3. Rate limits — Form submissions are rate-limited to 10 per IP per hour and 5 per email per hour. If the limit is exceeded, submissions will be rejected.

4. Installation access — Ensure the target repository has an active Scitor installation with the correct permissions.