Troubleshooting - Sagepilot Docs

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

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.
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.
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. 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.

`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.
`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.

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.

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