Troubleshooting
Symptom-first fixes for the issues we actually see: a blocked widget, a slow first request, detection misses, enrichment failures, and sign-in problems.
Start from your symptom. Every fix on this page is the real, currently-shipping remedy — and when something needs a human, the last section says exactly where to write.
The widget doesn’t appear
The most common cause is a strict Content-Security-Policy on your page. The widget injects its styles into its Shadow DOM with a style element, so a style-src that forbids inline styles blocks it — allow 'unsafe-inline' under style-src (the styles never leave the widget’s shadow root). Your browser console shows the CSP violation when this is the cause.
Also confirm script-src allows cdn.syncanix.com (where widget.js is served) and connect-src allows api.syncanix.com (where it talks).
Pages enforcing Trusted Types (require-trusted-types-for 'script') are supported: the widget boots and chats without feeding any string sink. Only if your policy ALSO restricts policy names with a trusted-types directive, allow syncanix-widget (bot-protection challenge), syncanix-widget-sw (offline service worker), and dompurify (answer sanitizer) — otherwise those optional features degrade gracefully while chat keeps working.
The first request is slow, or fails once and then works
On quiet workspaces the very first request after a long idle can take a few seconds while serverless capacity wakes up, and in rare cases it fails once. The widget retries its configuration load automatically. If you call the API directly, treat a single failing first request after idle as retryable.
Discovery found nothing, or picked the wrong framework
Run syncanix doctor first — it checks your Node version, detected framework, config validity, and API key in one pass. If detection picked wrong (mixed repos can confuse it), name the framework explicitly: syncanix init --framework <name>.
If discovery scanned folders it shouldn’t (vendored code, generated files), add them to .syncanixignore and re-run.
Enrichment failed, or you need to work offline
Pass --offline to write the catalog locally without uploading; with no model keys configured, syncanix init --offline --yes completes discovery without enrichment. The catalog file is deterministic, so re-running later doesn’t churn your review.
Sign-in problems
syncanix login stores a dashboard-generated token in ~/.syncanix/credentials (readable only by you); syncanix logout removes it. If uploads fail with an auth error, run syncanix doctor — it tells you whether the stored key resolves — then sign in again.
Changing a stored consent decision
Your enrichment-consent decision is stored in .syncanix/consent.json. To change it, delete the file and re-run syncanix init — the consent prompt runs again.