Troubleshooting

Start with the symptom you see, check the likely cause, and follow the fix. For most problems, the fastest first step is to reproduce the issue in the Playground (see test your agent) using the same role as the affected person, then open the session in Monitor to see each step the agent took. If you are stuck, send your Achilles contact the session reference.

Agent behavior

Symptom	Likely cause	Fix
Agent refuses a reasonable request	The request is outside its stated scope, or the person's role does not include that ability	Check the agent's scope in Agent Builder. In Roles, confirm the role has the ability. See roles and access.
Agent says it cannot help for one person but works for another	Their roles differ, or their role name from your system is not mapped	Open Roles and check the mapping for the role your system sends. Unmapped roles get the least access.
Wrong or vague answer	The procedure it relies on is missing or ambiguous, or the ability description is unclear	Add or clarify the procedure, rewrite the ability description, then add the question as a test case. See prepare your SOP.
Answer has an old figure	Your system had not yet updated, or the answer was from earlier in the conversation	Ask again in a fresh session. Figures come from your systems live.
Agent answers in the wrong language	Language guidance is missing or the model is weak in that language	Set the language in the persona and test other models in AI models.
Replies are cut off or "partial"	The agent reached its step limit before finishing	Ask it to continue, or raise the step limit for that agent.
Agent asks for approval every time	Approvals are on for actions that change records, by design	Keep this for sensitive actions. See approvals.

Abilities and data

Symptom	Likely cause	Fix
An ability returns an error	The system is unreachable, a credential expired, or an input was invalid	Open Datasources and run the connection test. Check the session steps in Monitor for the message.
Cannot connect the database	Wrong connection string, database firewall blocking Achilles, or the account lacks permission	Confirm host, port, and database name. Ask IT to allow the Achilles API address, and use a read-only account with access to the needed tables.
Connection works in a test but the agent has no data	The person's row limits filter everything out	Check the role's data rules and the claims in the user token. A missing claim returns nothing rather than everything.
Some fields show as masked	Masking applies to that role	Expected. Only roles you list as trusted see full values. See personal data.
Agent cannot see a table	The table was not selected during setup	Reopen the data step in Agent Builder and add it. See connect your data.
Saved a change but the agent behaves the same	The agent was not reloaded, or you are looking at an older session	Publish again, then start a fresh session.

Website widget

Symptom	Likely cause	Fix
Widget does not appear	Script blocked, wrong address, or missing agent key	Check the browser console for errors. Confirm the script address, agent key, and API address. See website widget.
Widget appears but messages fail with an authorization error	The token is missing, expired, or signed with the wrong secret	Ask IT to check the token is generated fresh per page load and that its lifetime has not passed. See integration overview.
Requests blocked in the browser	The website address is not in the channel's allowed origins	Add the exact site origin, including https, under the channel in Deployments.
"Too many requests" message	Per-user rate limit reached	Wait a moment. If it happens to normal users, ask IT to raise the limit.
Widget shows the wrong greeting or name	Looking at another agent or a cached page	Confirm the agent key, then hard refresh.

Handoff and channels

Symptom	Likely cause	Fix
Handoff does not fire	Handoff is off, or the trigger phrase does not match what people say	Turn on handoff and add the real phrases customers use. Test in the Playground. See human handoff.
Handoff fires but nobody is notified	The notification role has no contact, or email is not configured	Add a contact for the notified role and ask IT to confirm outbound email settings.
WhatsApp or Instagram gets no replies	Webhook not verified, wrong verify token, or channel disabled	Recheck the webhook address and verify token in your Meta settings, and confirm the channel is enabled. See messaging channels.
Messaging replies are delayed	Queue backlog or model rate limits	Check the model's readiness in the overview and consider a higher-capacity plan.

Voice

Symptom	Likely cause	Fix
No microphone button	Voice is not enabled for the agent, or hidden on the embed	Enable voice for the agent and remove the setting that hides it. See voice.
Browser cannot use the microphone	Permission denied or the page is not on HTTPS	Allow the microphone for the site and serve the page over HTTPS.
Voice connects then drops	A proxy is blocking WebSockets	Ask IT to allow WebSocket connections to the API address.
Speech is misheard	Wrong language setting or noisy audio	Set the expected language and test with real recordings.
Voice is not ready	Speech service is not configured	Ask your administrator to configure the speech provider.

Console and access

Symptom	Likely cause	Fix
Signed out unexpectedly	Console sessions expire after 12 hours	Sign in again.
A teammate cannot see an agent	They are not in that workspace	Add them under users and teams.
Import or save is rejected	The validation check found a problem	Read the message, which names the field. See the definition reference.
Sessions page is empty	The audit database is not connected	Ask IT to confirm the database connection. See self-hosting.