Troubleshooting
Common problems by symptom, with the usual cause and where to fix it.
Find your symptom below. If it is not here, ask the assistant inside the dashboard — it can see
your configuration.
| Symptom | Usual cause | Fix |
|---|
| Answers are vague or generic | No knowledge source attached | Attach one on the agent's Knowledge tab — see 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 |
| 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 |
| Behaviour changed unexpectedly | Someone edited the agent | Check version history |
| 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 |
window.AgentKit is undefined | Script tag loads after your init code — see the widget SDK |
| Some users get no reply | An allow or deny list is filtering them |
| Telegram bot silent | Token mistyped, or the webhook needs re-registering — see Telegram |
| WhatsApp worked then stopped | A temporary access token expired — see WhatsApp |
| Agent cannot message a WhatsApp user first | Expected — needs an approved template and an open 24-hour window |
| 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 |
| 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 — only exact match works. This is permanent |
| Agent will not read back a value it saved | The field is read-blocked, which is the safe default for personal data |
| 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 |
| Symptom | Usual cause |
|---|
| Allowance used faster than expected | Attachments each count as an interaction — see 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 organization |
| Cannot publish an agent version | Your plan is below the versioning tier, or a publish gate is blocking |
| 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 |
Ask the in-dashboard assistant, which can see your actual configuration, or contact support
through the dashboard.