Troubleshooting

Almost every problem is one of five things. This page is ordered by how often each one turns out to be the cause.

Start here

Open your site, open the browser console, and paste this. It tells you which of the three stages failed.

browser console

typeof window.Voicebox              // script executed?
!!document.querySelector("[data-voicebox]")  // mounted?
Voicebox("open")                    // renders?

"undefined" on the first line: the script never ran. Jump to the script isn't loading.
Function, but false on the second: the script ran and the config request failed. See wrong or inactive key.
Both fine, no button on screen: the floating trigger is switched off. See no button.

1. The script isn't loading

Open the Network tab and filter for widget.js.

Not in the list at all. The tag isn't on the page. On Webflow and Squarespace, custom code only runs on the published site, never in the editor preview. On WordPress, check you edited the active theme.
Blocked by Content Security Policy. The console says so explicitly. Add the two entries in Security & privacy. This is the single most common cause on established sites.
Blocked by an ad blocker. Some lists catch anything that looks like third-party analytics. Test in a private window with extensions disabled to rule it in or out.
A bundler ate it. In Astro use is:inline. In React, put the tag in the HTML shell rather than importing it from a component.

2. Wrong or inactive project key

Look for the request to /api/widget/pk_… in the Network tab. A 404 means the key doesn't match a project, usually a copied placeholder, a truncated paste, or a key regenerated after you installed it.

Copy it fresh from the Widget page. Keys are pk_ followed by a long random string, with no spaces or line breaks.

3. It loaded, but there's no button

If Voicebox("open") opens the panel, everything works and the floating trigger is simply hidden. Turn it back on under Widget → Trigger, or keep it hidden and open the panel from your own button, which is what Triggers covers.

If the button is there but sits under something else, the widget takes a very high stacking position inside its own root. An element on your page with an extreme z-index can still win. Check what is overlapping that corner, or move the widget to a different one in the studio.

4. Submissions are rejected

The panel opens, the message is written, and sending shows an error. The response from /api/ingest says which:

Status	Meaning	Fix
403	Origin not allowed for this project	Add the domain under Settings → Projects. Include staging.
403	Origin required	A server-side call to a project that has an allowlist. Use a project without one.
429	Too many submissions	That IP hit the hourly cap. Expected while testing repeatedly.
429	Not accepting feedback right now	The plan's allowance for this period is used up. Upgrade, or wait for the window to reset.
400	Validation failed	Usually an empty message or a rating outside 1-5.
404	Unknown project	The key doesn't match a project. See section 2 above.

Your users' words are never lost to metadata

If you pass more identity traits than fit, the extra traits are trimmed and the message still goes through. An over-filled identify() call cannot cost you someone's feedback.

5. Feedback arrives but no themes appear

Themes need a pattern before there is one to name. Below roughly twenty submissions per project you will see individual feedback in the inbox, scored and summarised, but few or no groups. That is the system being honest rather than inventing structure.

If you have plenty and still see nothing, check that analysis is switched on under Settings → General. The dashboard says so explicitly when it is paused. You can also force a pass with Regroup now on the overview rather than waiting for the scheduled run.

Styling looks wrong

An unstyled panel, rather than no panel, almost always means a style-src policy blocking the stylesheet inside the shadow root. Your page's own CSS cannot cause this, it genuinely cannot reach inside.

Still stuck

Email support@usevoicebox.dev with the URL, your project key (it's publishable, safe to send), and whatever the console printed. That is usually enough to answer without a back-and-forth.