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

# Troubleshooting

> Turn on SDK logging and fix the failures developers hit most often.

## Debug mode

Add `?taiDebug=true` to the URL of the page that embeds the agent, reload, and open the browser console. The SDK then logs every message it exchanges with the iframe, tool executions with their parameters and results, upload cache hits, and identity verification results.

```
https://example.com/pricing?taiDebug=true
```

The flag is read once when the script loads, so it has to be in the URL before the page renders.

## Common failures

| Symptom                                               | Cause                                                                                         | Fix                                                                                                                        |
| ----------------------------------------------------- | --------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `tai is not defined`                                  | Your code ran before the embed script loaded.                                                 | Put your code in a `teamAIChatbotReady` listener, or check `window.tai` before use.                                        |
| `teamAIChatbotReady` never fires                      | No `div[data-chatbot-id]` existed when the script ran, or the assistant ID is wrong.          | Render the div before the script, or call `initializeChatbot()` on the div you add later. Recheck the ID.                  |
| `ready()` never resolves                              | `tai.getInstance()` was called with an ID that has no div on the page.                        | Use the exact `data-chatbot-id` value.                                                                                     |
| `sendMessage()` resolves with `timeout`               | Wrong assistant ID, iframe blocked, or the page is offline.                                   | Confirm the iframe rendered, then check the network tab for `app.teamai.com`. Do not resend automatically.                 |
| `sendMessage()` resolves with `busy`                  | The assistant is still answering, or a specialist handoff is in progress.                     | Wait for `answerComplete` and send again. See [Handle busy](/sdks/embed-sdk/messages-and-status#handle-busy).              |
| `sendMessage()` resolves with `invalid_message`       | Empty or whitespace-only text.                                                                | Trim and check the text before sending.                                                                                    |
| Message sent on page load disappeared                 | You are on an embed script cached before the readiness fix.                                   | Hard-refresh. The current script waits for history before accepting a message.                                             |
| Message went to the anonymous chat after `identify()` | Verification failed, so the SDK logged an error and kept the chat anonymous.                  | Turn on debug mode and follow the [identity troubleshooting](/sdks/embed-sdk/identity-verification#troubleshooting) steps. |
| `uploadBlob()` rejects with "missing key"             | No `data-chatbot-embed-key` on the div.                                                       | Create a key on the agent's Channels page and add the attribute.                                                           |
| `uploadBlob()` rejects with "too large"               | Blob over 10 MB.                                                                              | Split or compress the file.                                                                                                |
| Tool registered but the agent never calls it          | The description does not tell the model when to use it, or `parameters` is not a JSON Schema. | Start `parameters` with `type: "object"`, and name the situation in `description`.                                         |
| Tool call returns nothing to the agent                | `execute` took longer than 30 seconds.                                                        | Return early with partial data, or move slow work behind your own API with a timeout.                                      |
| Context value not used in the answer                  | The key in `updateContext()` does not match `{{key}}` in the agent's instructions.            | Match the key exactly, including case.                                                                                     |
| Popover panel stays closed after `sendMessage()`      | The SDK does not open the panel.                                                              | Open it with the button before sending. See [Popover mode](/sdks/embed-sdk/messages-and-status#popover-mode).              |
| Two chat windows for one agent                        | `tai.initializeAll()` was called after the script already ran.                                | Remove the extra call. Use `initializeChatbot()` for late-added divs only.                                                 |
| Header still shows with `data-hide-header="true"`     | The attribute is on the wrong element.                                                        | Put it on the same `div` that carries `data-chatbot-id`.                                                                   |

## Timeouts at a glance

| Operation             | Timeout    | Outcome                                            |
| --------------------- | ---------- | -------------------------------------------------- |
| `sendMessage()`       | 35 seconds | Resolves with `code: "timeout"`.                   |
| `conversationReady()` | 30 seconds | Rejects with an `Error` whose `code` is `timeout`. |
| `getConversation()`   | 5 seconds  | Rejects.                                           |
| `resetConversation()` | 5 seconds  | Rejects.                                           |
| `uploadBlob()`        | 60 seconds | Rejects with `Upload timed out`.                   |
| Client tool `execute` | 30 seconds | Agent receives no result and continues.            |

## Getting help

Email [support@teamai.com](mailto:support@teamai.com) with the assistant ID, the page URL, and the console output from debug mode.