Sign in
Open console
Docs/Troubleshooting/Widget won’t load
docs · troubleshooting

Widget won’t load

troubleshooting

Resolve script, key, and allowed-domain errors in the embed.

A widget that never appears almost always comes down to one of three things: the embed script can't load, the key is wrong, or the page's origin isn't allowed by the server's CORS configuration. Walk the checklist before changing anything in the console.

Checklist

  1. The embed script tag is present and points at the correct CDN (NEXT_PUBLIC_WIDGET_CDN_URL), and the API gateway URL (NEXT_PUBLIC_API_GATEWAY_URL) is set.
  2. The embedded key is a valid publishable pk_ key — secret sk_ keys are never used in the browser.
  3. The page's origin is included in the server's ALLOWED_ORIGINS — this is the real CORS gate the widget request passes through.
Allowed domains is not the CORS gate — The Settings ▸ Allowed domains list is stored but is NOT enforced on any request path. Origin enforcement is the process-wide ALLOWED_ORIGINS environment variable only — adding a domain to the console list will not, by itself, let the widget load.

If it still fails

  • Open the browser console: a CORS error points at ALLOWED_ORIGINS, not the console allow-list.
  • A 401 from the gateway points at the key — confirm it is an active pk_ key for this workspace.
  • A missing script or 404 points at the CDN / API gateway environment variables in the host page.
referenceWidget embedDrop the widget on any page with a script tag and a custom element.
featureAPI keysCreate and rotate the pk_ and sk_ keys used by the API and widget.
featureAllowed domainsWidget embed allow-list (max 50). Not enforced on the request path — origin enforcement is the process-wide CORS env only.
Was this page helpful?