--- title: "Troubleshooting" url: "/troubleshooting" description: "Common problems by symptom, with the usual cause and where to fix it." productArea: troubleshooting audience: ["business-user", "developer", "admin"] tags: ["troubleshooting"] lastReviewed: 2026-08-14 --- # Troubleshooting (/troubleshooting) Find your symptom below. If it is not here, ask the assistant inside the dashboard — it can see your configuration. ## The agent gives poor answers [#the-agent-gives-poor-answers] | Symptom | Usual cause | Fix | | -------------------------------------------------------- | ------------------------------------------ | --------------------------------------------------------------------- | | Answers are vague or generic | No knowledge source attached | Attach one on the agent's Knowledge tab — see [knowledge](/knowledge) | | Says it does not know something that is in your document | Source still processing, or not attached | Check the source status is **completed** | | Ignores knowledge entirely | Answer mode is `tools_only` | See [answer modes](/guardrails/answer-modes) | | Refuses questions it should answer | `grounded_only` and the content is missing | Add the content to knowledge rather than loosening the mode | | Answers confidently but wrongly | Answer mode is too loose | Move to `grounded_only` and enable response validation | | Tone is inconsistent | Tone set in a skill instead of SOUL | Move it to the [SOUL file](/agents/core-prompt-files) | | Behaviour changed unexpectedly | Someone edited the agent | Check [version history](/agents/versioning) | ## Nobody can reach the agent [#nobody-can-reach-the-agent] | Symptom | Usual cause | | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- | | No response on any channel | Agent status is `draft` or `inactive` | | Widget does not appear | The site's domain is not in allowed origins — see [the web widget](/channels/web-widget) | | `window.AgentKit is undefined` | Script tag loads after your init code — see [the widget SDK](/build/widget-sdk) | | Some people get no reply | A deny list entry is filtering them — see [access control](/channels#access-control) | | Nobody gets a reply on one channel | The channel is **Restricted** and its allow list matches nobody | | A widget visitor is refused | Data table entries do not authorise widget visitors — see [the web widget](/channels/web-widget#restricting-who-can-chat) | | Telegram bot silent | Token mistyped, or the webhook needs re-registering — see [Telegram](/channels/telegram) | | WhatsApp worked then stopped | A temporary access token expired — see [WhatsApp](/channels/whatsapp) | | Agent cannot message a WhatsApp user first | Expected — needs an approved template and an open 24-hour window | ## Tools and data [#tools-and-data] | Symptom | Usual cause | | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | Agent never calls a tool | Tool not enabled on the agent, or its description is too vague | | Agent calls a tool at the wrong moment | Description describes the API rather than when to use it — see [tools](/skills-and-tools/tools) | | Agent cannot see a data table | No permission granted on the table's Permissions tab | | Agent sees no rows | A row scope rule found no matching identity — scope rules fail closed | | Cannot search a field by partial match | The field is encrypted — it matches on a whole value, or a whole word if set to Match any word. Never on a fragment | | Agent will not read back a value it saved | The field is read-blocked, which is the safe default for personal data | | Agent says it will do something, nothing happens | It described the action instead of performing it. It retries once and then reports the failure — if it persists, check the tool is enabled on the agent | | Agent cannot save a value to a choice field | The field has no options configured — add them on the table's Fields tab | ## Uploads and files [#uploads-and-files] | Symptom | Usual cause | | -------------------------------- | ---------------------------------------------------- | | Upload rejected | Unsupported type, over 30 MB, or no extractable text | | Scanned PDF produces nothing | Reprocess the source and force vision extraction | | Only part of a long PDF was read | Vision extraction caps at the first 50 pages | ## Usage and billing [#usage-and-billing] | Symptom | Usual cause | | -------------------------------------- | ------------------------------------------------------------------------------------------------------ | | Allowance used faster than expected | Attachments each count as an interaction — see [interaction counting](/reference/interaction-counting) | | Evaluation run cost more than expected | Judged cases add one interaction per case | | A feature is greyed out | It requires a higher plan — see [workspace](/organization) | | Cannot publish an agent version | Your plan is below the versioning tier, or a publish gate is blocking | ## Memory [#memory] | Symptom | Usual cause | | ----------------------------------------------- | ------------------------------------------------------- | | Memory toggle is locked | No business domain selected on the agent | | Agent does not remember an earlier conversation | Extraction runs after a conversation ends, not during | | Agent remembers something it should not | Edit or remove it under Contacts → the contact → Memory | ## Still stuck [#still-stuck] Ask the in-dashboard assistant, which can see your actual configuration, or see [getting help](/troubleshooting/support) for how to reach the team. ## Related pages [#related-pages] * [Guardrails](/guardrails) * [Channels](/channels) * [Glossary](/reference/glossary) * [FAQ](/troubleshooting/faq) * [Getting help](/troubleshooting/support)