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

# Troubleshooting

> Fix common Web SDK installation and integration problems.

Start by opening your browser's developer console on the page with the widget. Widget messages start with `[ChatWidget]`.

## The widget does not appear

| Check                                                                         | What to do                                                                                                                                                                                      |
| ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Console shows `init() requires a valid key parameter` or `Invalid key format` | The key is missing or malformed. Copy it again from **Channels** > your widget > **Embed Code**. It must look like `workspace_id:channel_id`.                                                   |
| `window.sagepilotWidgetReady` rejects                                         | The script could not download, or the channel could not be loaded. Check that a content blocker or your Content Security Policy allows `https://app.sagepilot.ai`, and that the channel exists. |
| The widget loads but no launcher is shown                                     | Check whether `hideNativeLauncherButton: true` is set. That option hides the launcher by design.                                                                                                |
| The launcher is hidden behind other elements                                  | Raise `closedZIndex` in `init()`. See [Configuration](/sdks/web/configuration).                                                                                                                 |
| The channel is turned off                                                     | Turn the channel on in Sagepilot.                                                                                                                                                               |

## My button does not open the chat

| Check                                                                | What to do                                                                                                                                                                                                                                                     |
| -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Console shows `Widget not initialized. Call init() first.`           | Your code ran before the widget was ready. Wait for `window.sagepilotWidgetReady`, or use the retry helper in [Open chat from your own button](/sdks/web/opening-chat#if-you-cannot-change-the-install-snippet).                                               |
| Console shows `Cannot read properties of undefined` for `ChatWidget` | The widget script has not loaded on this page, or your code ran before it. Confirm the snippet is on every page where the button appears.                                                                                                                      |
| Console shows `init() called more than once; ignoring repeat call.`  | The widget is installed twice, for example by both a theme snippet and the Shopify app embed, or by a single-page app on every route. Keep one installation. When the script loads twice, `window.ChatWidget` is replaced by a copy that cannot open the chat. |
| The button is added after page load                                  | Use a click listener on `document` that checks for `[data-sagepilot-open]`, as shown in [Open chat from your own button](/sdks/web/opening-chat). A listener attached directly to a button misses buttons added later.                                         |
| The button is a link and the page jumps or navigates                 | Call `event.preventDefault()` in your click handler.                                                                                                                                                                                                           |

## Identity problems

| `error` from `identify()`                                  | What to do                                                                                                                                                                 |
| ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `user_id is required`                                      | Pass a non-empty `user_id`.                                                                                                                                                |
| `Widget not initialized`                                   | Call `identify()` after `init()`. Wait for `window.sagepilotWidgetReady`.                                                                                                  |
| `Identity verification is enabled. user_hash is required.` | Identity verification is on for this channel. Generate `user_hash` on your server and pass it. See [Identity](/sdks/web/identity#identity-verification).                   |
| `Invalid identity verification signature`                  | The hash does not match. Make sure you sign the exact `user_id` string, use the current secret from the channel's **Identity** settings, and output lowercase hexadecimal. |
| `Identity request superseded`                              | A newer `identify()` or `logout()` call replaced this one. No action is needed.                                                                                            |

## Messages are not sent

* `not_initialized`: wait for `window.sagepilotWidgetReady` before calling `setDraft()` or `sendMessage()`.
* `not_ready`: the chat did not become ready within 15 seconds. In some browsers, such as Firefox, it also happens when your site's `Referrer-Policy` is `no-referrer`, because the chat cannot confirm which site embeds it. Use the default referrer policy, or `strict-origin-when-cross-origin`.
* `requires_input`: the visitor must complete the contact form or verification step in the chat.

See [Draft and send messages](/sdks/web/sending-messages#failure-codes) for every code.

## Still stuck?

Contact Sagepilot support with your site URL, the widget key, and a screenshot of the console messages.