Troubleshooting

The widget doesn't appear#

Check the browser console for the warning init requires endpoint and apiKey: one of the required options is missing. Also confirm the script tag actually loaded; a privacy extension can block third-party scripts, in which case allow your Worker origin in the extension.

Reports are rejected with a 4xx#

The two usual suspects: an apiKey that doesn't match the project, and a page origin that isn't registered in the project's allowed origins. Add every origin a widget lives on (including localhost for development) in the project settings.

Reports don't land in the dashboard#

Confirm the apiKey is a valid app token for the project you expect. Tokens are shown once at issue time; create a new one if it was lost. Reports can also sit in the offline queue on flaky connections and flush on the next page load.

No AI insight on a report#

Distillation is best-effort and runs asynchronously. A report can stay (undistilled) if the LLM provider is unavailable, the provider key is unset, or the distillation budget is exhausted. The raw text and attachments are unaffected, and the report can be distilled on a later pass.

Screenshots or replays never attach#

Both are consent-gated. If the tester denied the prompt (or it's still pending), nothing is captured. Choices persist in localStorage; clearing testosaurus:screenshot-consent or testosaurus:replay-consent triggers the prompt again. See Privacy & consent.

Stale bundle after an SDK update#

The bundle is cached immutably. Run npm run build: it stamps the current hash into every public page automatically, then commit the rebuilt bundle and pages and redeploy. To pin manually, read the current version from /testosaurus.version.json and bump the ?v= hash in your script tag.