Chapters

Chapter 12

Troubleshooting

Start with the visible symptom, then narrow the problem down.

SymptomWhat to check
A menu item or bot section is missingThe menu follows your roles. Ask an Administrator or Security Admin to check the roles on your account.
Changes to an API are not saved, or you see “API configurations are read-only for your role”Saved APIs need the API Integrator role. Ask an API Integrator to make the change, or ask for that role.
“Your role can view this bot but cannot change its design”Your roles allow reading the bot only. Flow changes need the Bot Designer role.
The bot cannot be publishedOpen the validation report and work through each issue: one Start flow, one entry per flow, connected steps, valid branch targets, declared variables, complete translations, and a staffed department for Live Agent steps.
An API step follows the Failure branchInspect the error in the run trace. Check the workspace connection, the request path, the variables, the expected status, the response mapping, and whether the remote service is available.
Knowledge returns a guarded responseConfirm that a relevant, current source is ready. Test a specific question and improve the source wording. A guarded response is correct when the evidence is not sufficient.
A value is missing or has the wrong typeCheck where the variable is declared and assigned. Review the input, API mapping, Set Variable, AI Router, or script output in the trace.
Untrained queries stays emptyCheck that transcript storage is on in Bot settings. The list fills only from live conversations, not from the playground.
A trained question is still not answeredIf it was added to an intent, publish the bot first. If it was added as an answer, add another answer that uses the customer’s own wording.
Observability shows a worker as Down or UnknownUnknown means the worker has not reported yet; Down means it has stopped. Ask your administrator to start the workers. Without the channel worker, WhatsApp messages are not delivered.
A close, fallback, or inactivity flow does not runConfirm that the flow is selected in Bot settings and is part of the published release.
An agent cannot claim a chatThe agent has reached their concurrent chat limit. Resolve a chat, or raise the limit under Users & agents.
The Agent inbox says “Agent access required”Ask an Administrator or Security Admin to give you the Agent or Supervisor role in a department.
The draft works but the live bot does notCheck that the intended version was published and that the deployment is switched on. Then check the embed script or WhatsApp number and test from the real channel.