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

# Error handling

> What users see when something fails, and how to diagnose it

The chat UI handles runtime errors for you: failed turns show a user-safe message in the conversation, and the widget stays usable. Your job is mostly diagnosis. This page maps the symptoms you might see to their causes.

## Symptom to cause

| Symptom                                                   | Likely cause                                                     | Fix                                                                                                                     |
| --------------------------------------------------------- | ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| Widget does not load or shows default branding            | **Mobile app** profile not deployed or not **Live**              | Deploy the profile under **Deploy > Mobile app**                                                                        |
| Chat fails immediately on every message                   | Invalid or revoked publishable key                               | Copy a fresh key from the **Embed** tab                                                                                 |
| Agent replies with a rate-limit message                   | Guardrail rate limits reached                                    | Review **Agent settings > Security**; see [Topic & rate controls](/user-guides/settings/topic-and-rate-controls)        |
| Agent replies "I can't help with that" to valid questions | Topic guardrails too strict, or missing knowledge                | Check **Security** settings and **Sources**                                                                             |
| Action returns a sign-in card unexpectedly                | Missing or inconsistent `endUserId`                              | Pass the same `endUserId` on every mount; see [Authentication & identity](/developer-guides/quick-start/authentication) |
| Navigation card click does nothing                        | `onNavigate` not wired (mobile) or listener script missing (web) | See [Embed navigation](/developer-guides/integration/embed-navigation)                                                  |

<Note>
  Guardrail rate limits appear as agent text in the conversation, not as an HTTP error, so users always get a polite response rather than a broken widget.
</Note>

## Observing failures

* **Chat logs** and **Inbox** in the dashboard hold the full transcript of every conversation, so you can see exactly what the user asked and how the turn failed.
* [Conversation Evals](/user-guides/analytics/conversation-evals) score real conversations against quality criteria and point at which part of the system caused a low score.
* The `onAgentDone` callback fires even for turns that end in an error message, so analytics can count failed turns.

## Escalation as a safety net

Configure an [Escalate to human](/user-guides/actions/escalate-to-human) action so that when the agent cannot help, users have a path to a person instead of a dead end.

<CardGroup cols={2}>
  <Card title="Activity" icon="inbox" href="/user-guides/agent-management/activity">
    Transcripts in Chat logs and Inbox.
  </Card>

  <Card title="Guardrails" icon="shield" href="/user-guides/settings/guardrails">
    Safety controls that shape error behavior.
  </Card>
</CardGroup>