> ## Documentation Index
> Fetch the complete documentation index at: https://docs.circuit.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Chat widget troubleshooting

> Diagnose and fix the most common Circuit chat widget problems, from a missing bubble to failed messages.

Work through the symptom that matches what you see. Most problems surface in the browser's developer console, so open it first (F12 in most browsers, then the Console and Network tabs).

## Bubble does not appear

**Console shows a `console.warn` about the chatbot config.**
The launcher fetches `GET /chat-bot/config` on page load. If that call fails for any reason (network error, non-2xx response, malformed JSON, missing or revoked key), the launcher logs a warning and renders nothing. Check:

* The script tag's `src` ends with `?apiKey=YOUR_AGENT_KEY`.
* The key has not been revoked in the agent's Chatbot settings.
* There are no network errors on the config request in the Network tab.

**Console shows a CSP violation for `script-src`.**
Your site's Content Security Policy is blocking the launcher script. Add `https://chat-embed.circuit.ai` to your `script-src` directive. See [Content Security Policy](/it/chat-widget/security#content-security-policy).

**No console errors and no bubble.**
Confirm the script tag is present in the served HTML (use View Source, not the DOM inspector) and that a request for `launcher.js` appears in the Network tab. Tag managers and CMS custom-code fields sometimes strip script tags or apply them only to certain pages.

## Messages fail with 403 origin not allowed

The page's hostname is not on the API key's Allowed Website Domains list. In the agent's Chatbot settings, open the key and add the exact hostname shown in your browser's address bar.

Rules:

* `example.com` and `www.example.com` are different entries. Add both if you serve from both.
* Enter hostnames only, without `https://` or a port number.
* Staging and localhost hostnames need their own entries.

The check fails closed: a key with an empty allowed domains list rejects every request. See [domain allowlisting](/it/chat-widget/security#domain-allowlisting).

## Messages fail with 401

The key is missing, wrong, or has been revoked. Create a new key in the agent's Chatbot settings, update the `src` in the script tag, and hard-reload the page.

## Messages fail with 429

The key has exceeded 60 requests per minute, counted across all visitors using that key. The `X-RateLimit-Reset` response header shows when the window resets. If normal traffic reaches this limit, contact the Circuit team.

## CSP violation on frame-src

The launcher injects an `<iframe>` pointing to `chat-embed.circuit.ai`. Add `https://chat-embed.circuit.ai` to your `frame-src` directive. The launcher script and the iframe share the same origin, so the same host covers both.

## Conversation resets between page loads or messages

The SPA stores the session token in `localStorage`. If `localStorage` is blocked (strict browser privacy settings, extensions, or private browsing mode), the widget still works but each page load or, in some configurations, each message starts a new chat. This is expected behavior in those environments.

Sessions also expire after 24 hours regardless of browser settings.

## Widget hidden behind page elements

The bubble and iframe render at `z-index: 2147483647`, the maximum CSS integer value. Only host-page elements with a stacking context above this value can cover the widget, which is not possible using a standard `z-index` value. If your page elements overlap the widget, check for transformed or positioned ancestors with unusually high stacking contexts.

## Position or color changes do not appear

The config response is cached for 60 seconds. Save your changes in the Chatbot settings, wait up to 60 seconds, and hard-reload the page to bypass the browser cache. See [configuration](/it/chat-widget/configuration#how-changes-propagate).

## Still stuck?

Contact the Circuit team with: the page URL, the chatbot key name (never the key value itself), the browser console output, and the failing request's status code from the Network tab.