Troubleshooting - TeamAI Docs

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.
`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 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.
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 with the assistant ID, the page URL, and the console output from debug mode.

​Debug mode

​Common failures

​Timeouts at a glance

​Getting help

Debug mode

Common failures

Timeouts at a glance

Getting help