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

# Widget troubleshooting

> Fix common AI Chat Widget issues such as a missing embed, repeated identity prompts, missing history, and custom component failures.

Before debugging, have these ready: the page where the widget is embedded, the widget mode you are using (HTML, React, or headless), the identity model you chose, and one recent conversation if possible.

<Tip>
  Looking for setup guidance? See [Install Widget](/widget/install-widget), [Mobile Support](/widget/native-mobile), [Authentication](/widget/authentication), and [Conversation Sessions](/widget/conversation-sessions).
</Tip>

<Info>
  Can't reproduce a styling or option issue locally? Open the **[Playground](/widget/playground)** to run the widget in isolation with a known-good config and compare behavior.
</Info>

## Common Troubleshooting Scenarios

| Symptom                                                            | Likely cause                                                                                                                    | What to do                                                                                                                                                                                         |
| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Widget does not appear**                                         | Missing script, wrong widget token, or the widget is mounted in the wrong place                                                 | Re-check the embed snippet, confirm the widget token from your [OpenCX dashboard](https://platform.open.cx/channels/configure/widget), and verify whether you intended a floating or inline embed. |
| **Visitor is asked for details again or cannot see earlier chats** | The widget is using an anonymous or non-verified identity, or browser storage was reset                                         | Decide whether the visitor should stay anonymous, use `collectUserData`, or receive a verified `user.token`. If history must work across devices, use server-side authentication.                  |
| **Signed-in customer still cannot see the right history**          | The widget is using `user.data` instead of `user.token`, or history should be scoped with `externalId`                          | Verify that your backend is calling `/widget/authenticate-user`, then pass the returned token as `user.token`. If the same email can belong to multiple accounts, add `externalId`.                |
| **Custom action result shows as plain text instead of your UI**    | The component key does not match the action `operation_id`, or your headless renderer is not branching on the right action name | Re-check the component mapping, confirm the action name, and make sure your component has a fallback state for missing payload data.                                                               |

<Info>
  Most widget issues come from one of three places: the [embed path](/widget/install-widget), the [visitor identity model](/widget/authentication), or [custom rendering logic](/widget/custom-components). Start there before assuming the problem is in the AI itself.
</Info>

## Identity And History Checklist

Work through these in order if history is the problem:

1. **Check whether the visitor is anonymous, non-verified, or verified.**
2. **Confirm whether your app is passing `user.data` or `user.token`.**
3. **Decide whether cross-device history is actually required.**
4. **Add `externalId` if one person can belong to multiple accounts or workspaces.**
5. **Retest with the same browser and then with a second device.**

## Expectations And Limits

| Area                  | Detail                                                                                                                                           |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Returning history** | Newest conversations appear first when history is available for that identity.                                                                   |
| **Resolved sessions** | Resolved sessions remain in history, but they are not active chat threads.                                                                       |
| **File uploads**      | Files larger than **5 MB** are rejected.                                                                                                         |
| **Custom UI**         | If your custom renderer does not match the action name or payload, the widget falls back to normal message rendering or your own fallback logic. |

***

## Related Documentation

<CardGroup cols={2}>
  <Card title="Install Widget" icon="plug" href="/widget/install-widget">
    Re-check your embed path, token, and launcher mode.
  </Card>

  <Card title="Authentication" icon="shield-check" href="/widget/authentication">
    Fix identity mismatches and cross-device history problems.
  </Card>

  <Card title="Conversation Sessions" icon="route" href="/widget/conversation-sessions">
    Re-check how history, resolution, and handoff should behave.
  </Card>

  <Card title="Mobile Support" icon="phone" href="/widget/native-mobile">
    Re-check WebView, identity, and mobile support setup.
  </Card>
</CardGroup>