testosaurusdocs
Browse docs
On this page

Troubleshooting

The widget writes a console line starting with [testosaurus] for every problem it can name. Open the browser console on the page and look for it first; the lines below are quoted exactly.

The widget doesn't appear

Check the console. [testosaurus] init requires an apiKey; widget not mounted means apiKey was missing or empty. Confirm the script tag actually loaded: a privacy extension can block third-party scripts, in which case allow testosaurus.dev in the extension, and a Content Security Policy can block it too (see Content Security Policy).

[testosaurus] widget was removed by the page; not re-attaching means your page deleted the widget more than ten times in a second, so the widget stopped putting it back. The widget lives in <body>, or in <html> when <body> has a transform, filter, contain or similar style that would pin a fixed launcher to the body instead of the window. React 18 apps that hydrate the whole document (hydrateRoot(document) can remove nodes React did not render, including the widget, and the widget sits outside <body> only when <body> has one of those styles. Put those styles on a wrapper element inside <body>, and call Testosaurus.init after hydration has finished, for example from useEffect.

The panel says "Feedback isn't available on this page yet."

The widget mounted, but it could not get what it needs to send reports, and Send stays disabled. The console names the reason:

  • [testosaurus] could not load the project config: add this site's host to the allowed addresses in settings → install & domains. — the host is not in the project's allowed addresses, or the request was blocked before it reached Testosaurus. A browser that cached the widget before this wording changed may still print [testosaurus] could not load the project config: add this site's host under App settings, Installation, Allowed domains. It means the same thing: add the host under settings → install & domains → Allowed addresses.
  • [testosaurus] could not load the project config: check the apiKey passed to init. — the token is not valid for any project. Copy it again from settings → install & domains → App tokens; tokens stay listed and copyable, and a revoked token stops working immediately.
  • [testosaurus] could not load the project config: this browser is offline; reload the page once the connection is back.
  • [testosaurus] bot protection is still being set up for this project; checking again shortly. and [testosaurus] bot protection is not ready for this project yet; reload the page in a minute. — the project has no bot-protection widget yet. Wait a minute and reload. If it persists, open settings → install & domains → Bot protection and retry bot protection.

Reports are rejected with a 4xx

Every rejection is logged as [testosaurus] report rejected <status> <code> with a hint. The usual suspects: domain_mismatch, a page host that is not in the project's allowed addresses (add it, with every host a widget lives on, including localhost for development); 401 or 404, an apiKey that does not match the project; verification_required or verification_failed, see the next entry. The Offline queue page lists what the widget does with each answer.

Bot protection fails

[testosaurus] could not get a verification token; <reason> names the reason. When the page does not let the challenge frame load, the whole line reads [testosaurus] could not get a verification token; bot protection did not load; check the project sitekey and that the page allows frames from the Testosaurus endpoint (CSP frame-src). Allow frame-src https://testosaurus.dev in the page's Content Security Policy and check the project's sitekey under settings → install & domains → Bot protection. When the frame did load, the reason is bot protection reported: … followed by what the challenge said. timed out waiting for the challenge means it gave no answer within twenty seconds, asked once more and again got none (or no answer within two minutes once a challenge is showing). bot protection reported: the verification frame reloaded before it answered means the frame reloaded during both attempts.

If the project uses its own Turnstile widget (BYOK) instead of the platform widget, the challenge still runs on testosaurus.dev, so that widget's hostname list must include testosaurus.dev, not only your own site. Without it every report is refused with verification_failed.

Reports don't land in the dashboard

Confirm the apiKey is a valid app token for the project you expect; tokens are listed in settings → install & domains → App tokens and can be copied any time. Reports can also sit in the offline queue on flaky connections: [testosaurus] could not reach the server; the report is saved and will send when the connection returns. is logged, and the queue flushes on the next page load. [testosaurus] queued report dropped means a saved report was refused for good and removed from the queue.

No AI insight on a report

Analysis is best-effort and runs asynchronously. A report stays (undistilled) or shows Analysis skipped or Analysis failed for one of these reasons:

  • The workspace has no included AI analysis or AI credit left this month. Add credit or wait for the monthly reset under settings → billing & usage.
  • The daily AI spend cap (€2.00 per workspace per UTC day) was reached. Analysis resumes after 00:00 UTC.
  • AI analysis is turned off for the project.
  • The model provider returned no usable answer, or the analysis failed. Insights says how many reports couldn't be analyzed and links to your reports.

The raw text, context and attachments are unaffected. A top-up queues the reports skipped for lack of credit again right away. Reports skipped by the daily cap are queued again by a daily job after the cap resets, and those skipped for lack of credit on the next daily run once the workspace has credit. You can always open a report and choose Re-analyze.

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. When a capture or upload fails, the console says [testosaurus] Screenshot capture failed; the report is sent without it. or Session replay upload failed; the report is sent without it. and the report records the reason. See Privacy & consent.

A dialog closes or loses focus when someone uses the widget

The widget stops its keyboard, focus and pointer events at its own host element, and it moves into an open modal <dialog> so it stays usable there. Dialog libraries that dismiss on an "outside" interaction can still treat the widget as outside. In Radix UI, ignore interactions that start inside the widget host, #testosaurus-root:

tsx
const insideWidget = (event: Event) => (event.target as Element | null)?.closest?.('#testosaurus-root');

<Dialog.Content
  onInteractOutside={(event) => { if (insideWidget(event)) event.preventDefault(); }}
  onFocusOutside={(event) => { if (insideWidget(event)) event.preventDefault(); }}
/>

Trusted Types

The widget creates two Trusted Types policies: testosaurus builds its panel, and html2canvas-pro is made by its screenshot library when it clones the page. A page that sends require-trusted-types-for 'script' together with a trusted-types allow-list must list both: trusted-types testosaurus html2canvas-pro. Without html2canvas-pro in the list, screenshots are skipped: the console says [testosaurus] Screenshot capture failed; the report is sent without it. and the report goes out without the image. Pages without Trusted Types enforcement need nothing.

Stale bundle after an SDK update

Browsers cache testosaurus.js for a year under its exact URL, so while your script tag keeps the same ?v= value, returning visitors keep the bundle they first downloaded. Open testosaurus.version.json, or copy the script tag from settings → install & domains → Snippet, and use the current hash as the ?v= value of your script tag, then redeploy your site. For a demo or evaluation you can point the tag at https://testosaurus.dev/testosaurus.latest.js, which is revalidated on every load, but keep the pinned URL in production. If you installed the npm package, update testosaurus-sdk and rebuild your app instead.

My coding agent says "needs authentication"

The MCP client could not authenticate to https://testosaurus.dev/mcp. Either TESTOSAURUS_SK is not set in the shell that started the agent (restart the agent from a shell that has it), or the access key was revoked. Create a new key under settings → agent access → Access keys. See Coding agents & MCP.

Something unclear?Let us know