Troubleshooting Guide

Diagnostic steps for the most common issues. Work through each section from top to bottom — the checks are ordered from most to least likely cause.

Emails not arriving as Issues/Discussions

Work through this checklist in order:

1. Check the GitHub App installation — Go to github.com/settings/installations (personal) or github.com/organizations/[your-org]/settings/installations (org). Confirm Scitor is installed and has access to the correct repository. If it’s missing, reinstall from the GitHub Marketplace.

2. Verify the forwarding address — Open the welcome issue in your repository to find your exact Scitor inbound address (e.g. abc123@in.scitor.io). Copy it directly from there — don’t rely on memory. Confirm your email provider is forwarding to this exact address.

3. Send a direct test — Send an email directly to your Scitor inbound address (not via the forwarding rule). If it arrives as a GitHub Issue, the problem is in your forwarding rule, not Scitor. If it doesn’t arrive, the installation or inbound pipeline has an issue — contact support.

4. Check for a blocked sender — The sender may have been previously blocked. Comment /unblock-sender on any issue to see if that resolves it.

5. Check the spam score — Emails with a spam:high label are filtered. Check the sender’s email authentication (SPF, DKIM, DMARC) and ask them to send from a different address to test.

6. Check forwarding rules for conditions — Some email providers only forward when certain conditions are met (e.g. “from external senders only”). Confirm the rule has no conditions that could prevent forwarding.

/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 /generate-report to check your current usage.

3. Email provider — Outbound email requires a configured email provider on Scitor’s side. If /send fails and your plan limit isn’t exceeded, contact support so we can check the provider configuration for your account.

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 /billing.

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 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.

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

Scitor has two separate “custom domain” features. Check which one you’re configuring:

Custom docs domain (/docs domain add)

If your knowledge-base site isn’t resolving on your custom domain:

1. CNAME record — Verify the CNAME record points to docs.scitor.io at your DNS provider. Apex/root domains (e.g. yourcompany.com) are not supported — use a subdomain like docs. or support..
2. Verification — Run /docs domain verify to re-check. Scitor registers the hostname with Cloudflare for SaaS, which provisions SSL automatically once DNS resolves.
3. DNS propagation — Changes usually propagate in minutes but can take a few hours. Check dnschecker.org.
4. SSL pending — If DNS resolves but the site shows a certificate error, give it a few more minutes; Cloudflare provisions the certificate after DNS validation completes.

Custom email sender domain (/authenticate-domain)

If outbound emails aren’t sending from your custom address:

1. DNS records — Verify the three CNAME records returned by /authenticate-domain are present at your DNS provider. They must be DNS-only (no Cloudflare proxy).
2. Verification — Run /verify-domain to see which records are still missing or invalid.
3. DNS propagation — Changes usually propagate in minutes but can take a few hours.
4. From address — Once verified, run /set-from-address with an address on the authenticated domain. The from-address local part (support@, help@, etc.) is up to you.

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.

Chatbot giving wrong answers or no answers

The chatbot answers only from your knowledge base. Wrong or missing answers almost always mean a docs problem, not a chatbot problem.

If the chatbot says it doesn’t know:

1. Check the knowledge base — Visit your docs site and search for the answer yourself. If it’s not in the docs, the chatbot can’t find it either. Add or update the relevant page.

2. Check the docs path — Confirm chatbot.enabled: true is set and docs.path points to the right folder in scitor.yaml. If the docs path is wrong, no content gets indexed.

3. Wait for the index to refresh — After a docs push, the search index refreshes within a few hours. If you just updated a doc, wait and try again.

4. Check for PDF size limits — PDFs over 4 MB are skipped during indexing. Convert large PDFs to Markdown, or split them into smaller files.

If the chatbot gives an incorrect answer:

1. Find the source — Ask the same question in your docs site search. The chatbot synthesises its answer from whatever the search returns — if the docs contain incorrect information, the chatbot will repeat it.

2. Update the docs — Fix the incorrect or misleading content in the source Markdown file and push the change. The chatbot will use the updated content after the next index refresh.

3. Check the Knowledge Gaps page — Go to Insights → Knowledge Gaps in your dashboard. Questions marked with 👎 feedback appear there and reveal which topics need better documentation.

4. Avoid conflicting content — If the same topic is covered in multiple docs with contradictory information, the chatbot may blend them. Consolidate or cross-link conflicting articles.

Chat widget not appearing on the page

If the chat bubble doesn’t show up after adding the script tag:

1. Check the script tag — Confirm the src URL is exactly https://api.scitor.io/widget/chat.js and that data-form has a valid form ID. Any typo silently prevents the widget from loading.

2. Check browser console — Open DevTools → Console. A script load error or a data-form validation error will appear there.

3. Confirm chatbot is enabled — Verify chatbot.enabled: true is in your scitor.yaml and the change has been pushed to the default branch.

4. Check the plan — The chatbot is an Enterprise plan feature. Run /billing on any issue to confirm your plan.

5. Check allowed origins — If you’ve configured chatbot.allowed_origins in scitor.yaml, the widget only loads on those domains. Confirm the current page’s domain is in the list.

6. Hard-reload the page — The widget script is cached for 1 hour. If you just made a change, try a hard reload (Ctrl+Shift+R / Cmd+Shift+R) or open an incognito window.

Permission error on a slash command

If Scitor posts a “permission denied” or “insufficient access” comment:

1. Check your repository role — Most commands require Write access. Triage-level collaborators cannot use /send, /followup, or AI commands. See Team Management for the full permission reference.

2. Check if you’re a collaborator — You must be a direct collaborator or member of a team with access to the repository. Having admin access to the organisation is not sufficient on its own if you’re not added to the specific repository.

3. Accept the invitation — If you were recently added as a collaborator, check your email for a GitHub invitation. You must accept it before your permissions take effect.

Attachments not appearing on issues

If email attachments aren’t showing up in the GitHub Issue:

1. Check file size — GitHub has a 10 MB limit per attachment. Files over this size are silently skipped.

2. Check file type — Certain file types are blocked by GitHub (e.g. .exe, .zip in some configurations). Check your repository’s settings and the sender’s original attachment type.

3. Check plan limits — Attachment handling requires the Scitor GitHub App to have Contents: Read permission on the repository. Confirm this under your GitHub App installation settings.

4. Inline images — Images embedded inline in an email (not as attachments) are extracted and attached separately. If the image is very small (tracking pixels) it may be filtered out automatically.