Troubleshooting: Common Issues and Solutions

Open the browser’s console and its Network panel, reload the page, and find your problem in the table. The sections below it explain the longer fixes.

Find the cause

What you see	Cause	Fix
No buttons, no error	The tag has no data-endpoint, or a JSON config block has no endpoint	Add data-endpoint="https://qaid.dev/api/feedback" (or endpoint in the block)
No buttons, and an error naming crypto.randomUUID	An http:// page with a version older than 1.8.0 pinned in src	See “The widget stops on an http:// page” below
No buttons for one visitor only	They clicked the ✕ once	See “A visitor says the buttons vanished” below
embed.js fails with 404 or ERR_BLOCKED_BY_CLIENT	A wrong src, or an ad blocker	Check the src, or host the files yourself
“Refused to load” or “Refused to connect” in the console	Your Content Security Policy	See “Allow the widget in your Content Security Policy” below
Two sets of buttons	The script tag and new QaidFeedback() both ran	Keep one
Buttons in the corner, not in your element	The container selector matched nothing when the widget started	Make sure the element exists before the widget loads
“QaidFeedback is not defined”	No script defines that global	import { QaidFeedback }, or with the UMD build use Qaid.QaidFeedback
The POST goes to your own site and fails	data-endpoint is a relative path such as /api/feedback	Use the full https://qaid.dev/api/feedback
The POST succeeds, but the item is not in your inbox	The tag has no data-api-key, or a key from another project	Copy the key from this project’s Settings → API Keys
The POST answers 400, 401, 403, 410 or 429	Qaid refused the report	See “Feedback never reaches the dashboard” below
Send closes the box with no thank-you	The first POST failed, so there was nothing to add a message to	Check that POST’s status
“Message not sent” after Send	Qaid refused the message, or the network dropped it	Check the status of the PATCH to /api/feedback/ and the item ID
“Domain not allowed” (403)	The page’s host is not the project’s Domain Restriction	See “Feedback is refused from another host” below
Items have no screenshot or console lines	The project owner is on Free	See Free vs Pro
No record button	captureVideo is off, or the browser cannot record the screen	See “Recording doesn’t start” below
A dashboard button opens the plans window	That feature is Pro, and the project owner is on Free	See “A dashboard button opens the plans window” below

Here the vote is saved, then the connection drops before the message gets through:

Nothing appears on the page

A working tag has an endpoint and a key:

<script
  src="https://unpkg.com/@qaiddev/thumbs-embed@1.9.0/dist/embed.js"
  defer
  data-api-key="YOUR_PROJECT_KEY"
  data-endpoint="https://qaid.dev/api/feedback"
></script>

Without data-endpoint the widget does not start and prints nothing. A <script type="application/json" data-feedback-config> block on the page replaces the tag’s attributes completely, so it needs its own endpoint and apiKey. A block that is not valid JSON is skipped without a word.

In the Elements panel, look for a div with data-qaid-embed near the end of <body>. If it is there, the widget started: the problem is placement or stacking, covered below.

Allow the widget in your Content Security Policy

A strict policy blocks the widget’s script, its report and its screenshot helper. Add these sources to what you already allow:

Content-Security-Policy: script-src 'self' https://unpkg.com https://qaid.dev; connect-src 'self' https://qaid.dev; style-src 'self' 'unsafe-inline'

The widget writes its own <style> elements, hence 'unsafe-inline'. If you host the files yourself, your own origin replaces unpkg.com.

The widget stops on an http:// page

thumbs-embed 1.8.0 or later runs on plain http:// pages. An older version pinned in src stops there with an error naming crypto.randomUUID(), before drawing anything. Change the version in src, or serve the page over https://.

Screen recording still needs a secure page: https://, localhost or 127.0.0.1.

A visitor says the buttons vanished

The ✕ beside the buttons hides the widget for that visitor for good. It is stored in their browser as qaid_hide_feedback_ followed by your project key. To bring it back, remove that key in Application → Local Storage. To stop it happening, set hideDismiss (data-hide-dismiss="true"). See Conditional display.

Feedback never reaches the dashboard

Find the POST to https://qaid.dev/api/feedback in the Network panel and read its status:

Status	Message	Fix
400	“API key is required” or “Missing required fields”	Add data-api-key with a key from project Settings → API Keys
401	“Invalid API key”	The key is wrong or was revoked. Copy a live one from API Keys
403	“Domain not allowed”	See “Feedback is refused from another host” below
410	“Project is archived”	An archived project cannot be restored. Use a key from a live project
429	“Monthly feedback limit (100) reached”	The project used its month. Free takes 100 a month per project, Pro 10,000. It resets on the 1st

A request that failed with no status at all was blocked in the browser: an ad blocker, a privacy extension, or a service worker. An http:// endpoint on an https:// page is blocked as mixed content, which can look like a CORS error. Qaid’s endpoints accept requests from any site, so a real CORS error usually means data-endpoint points somewhere else.

Feedback is refused from another host

The project’s Domain Restriction (project Settings → General) limits where feedback can come from. With example.com saved, Qaid accepts pages on example.com, www.example.com and any subdomain such as app.example.com. Everything else gets 403 “Domain not allowed”, including a staging site on another domain and a preview URL from your host. localhost and 127.0.0.1 are always accepted.

To collect from more places, clear the field, which accepts every site, or use a separate project for staging. The same check applies to recordings and quest responses. See Project settings.

Items arrive without screenshots, console lines or video

These depend on the project owner’s plan, not yours:

1. Screenshots and console lines are kept on Pro only. On Free the widget still sends them, and they are dropped.
2. Recordings are refused on Free with 403 “Video recording requires a Pro plan”.

On Pro, a missing screenshot on phones, or with screenshotMethod: "dom", usually means https://qaid.dev/lib/html2canvas.min.js could not load; the console says “html2canvas failed to load”. Items sent from localhost or a private address such as 192.168.x.x never get one from Qaid either: Capture Screenshot answers “Only public web pages can be captured”, because Qaid’s servers cannot open that page. See Screenshot capture.

A dashboard button opens the plans window

On a project whose owner is on Free, these open the plans window, show a Pro prompt, or are missing:

1. Capture Screenshot, team invitations, escalation rules, webhooks and Slack.
2. Regenerate with AI on Insights.
3. The dashboard assistant, which answers “AI assistant requires a Pro plan”.
4. The Platform API tab. Only the API reference goes by your own plan.
5. AI PR Fix and Copilot Fix, which do not show at all.

The owner’s plan counts, so an invited owner or member on Pro still sees the prompt. See Free vs Pro.

The buttons look wrong or can’t be clicked

The widget draws inside a shadow root, so your page’s CSS cannot reach it. Only inherited properties cross in: font, color, line-height and direction. To change its look, use its settings (data-positive-color, data-negative-color, data-marker-color) or pass CSS through the css option. See Styling the modal.

If you can see the buttons but not click them, something transparent sits on top. The widget’s z-index is 50 by default; raise it with data-zindex. If raising it changes nothing, the widget sits inside an element that makes its own stacking context (a transform, a filter, or opacity below 1). See Position and placement.

On a touch screen, a drag longer than a few pixels scrolls instead of picking an element. A tap picks.

Recording doesn’t start or never arrives

1. No record button: captureVideo is off, the page is not https://, or the browser cannot record the screen. Phone browsers generally cannot.
2. The share prompt closes and nothing happens: the visitor cancelled, or shared a window or the whole screen. Only the current tab is recorded.
3. A managed work browser may block screen sharing outright. You cannot change that from the page.
4. The review says “Your recording could not be sent.”: the project is on Free (403), or the tag has no data-api-key (400). “This recording is too large to send” means the file is over 50 MB (413). Look for the POST to /api/feedback/video.

See Video feedback.

Still stuck

Open an issue at github.com/qaiddev/thumbs-embed or email team@qaid.dev. Send your browser and version, the console output, the status and response of the failed request from the Network panel, your script tag exactly as it is on the page, and the steps that cause it.