Common issues

Diagnose and fix the most frequent agent issues with step-by-step troubleshooting.

Most issues fall into a handful of patterns. Before you open a support ticket, run through the checks below.

Quick reference

Symptom	Likely cause	Quick fix	Where to look
My edit isn’t live	You saved in Sandbox but didn’t promote.	Promote the new version in Deployments > Environments.	Environments & versions ↗
The agent still uses the old answer	Cached variant or conflicting topic.	1) Clear your browser cache / soft-reload. 2) Check if another topic has similar sample questions and higher priority.	Managed Topics ↗
Calls aren’t transferring	Wrong number format, SIP error, or firewall.	Confirm Route starts with + and country code. If SIP, double-check URI and headers. Test in Sandbox first.	Routing and handoffs ↗
Analytics show zero calls	Dashboard filtered to the wrong environment or date.	Switch environment to Live and widen the date range.	Dashboards overview ↗
CSV import failed	Header names or file encoding off.	Re-export a fresh CSV, copy-paste rows, save as UTF-8, re-import.	CSV imports ↗
I can’t edit anything	Read-only permissions.	Ask a project admin to grant you Editor in User management.	Invite users ↗
Audio is silent or distorted	Voice config mismatch or bad network.	Check Channels > Voice > Voice Configuration for the correct TTS voice. Test your network or try another device.	Voice config ↗
Agent answers a totally different question	Mis-matched topic or ASR error.	Review the conversation, tag Wrong transcription or Missing topic, and fix accordingly.	Conversation review ↗

Knowledge base issues

Agent gives a wrong or unexpected answer

Diagnosis steps:

1. Open the conversation in Conversations and enable Topic citations in the diagnosis panel.
2. Check which topic was retrieved — is it the right one?
3. If the wrong topic was retrieved, the sample questions or topic names may be too similar between topics. Make them more distinct.
4. If the right topic was retrieved but the answer is wrong, update the Content field.

Common causes:

• Two topics with overlapping sample questions — the retriever picks the wrong one
• Topic name is too vague (e.g., info or general) and matches too broadly
• Content is outdated or incomplete

Agent says 'I don't know' for a topic that exists

Diagnosis steps:

1. Check that the topic has been published and promoted to the environment you are testing in.
2. Verify the topic has sample questions — without them, retrieval accuracy drops significantly.
3. Test different phrasings. If only very specific wording triggers the topic, add more varied sample questions.

Common causes:

• Topic exists in Sandbox but hasn’t been promoted to Live
• Sample questions are too few or too narrow
• Topic name is not semantically related to the user’s query

Agent ignores the Actions section

When a topic instructs the agent to both say something and call a function in the same turn, the agent may do one but not the other. This is a common anti-pattern.

Fix: Structure actions so the agent only has one task per turn. If you need to say something and then call a function, split the instruction across turns — let the agent deliver the answer first, then handle the action in a follow-up.

Voice and audio issues

Voice speed change isn't reflected in calls

The change may be pulling from cached audio. Go to Audio Management, find the specific audio clip, update the speed setting, and regenerate the audio.

Agent mispronounces a word or brand name

Use the Pronunciations feature in Audio Management. You can provide IPA notation, SSML overrides, or regex-based corrections. See Audio Management for details.

Disclaimer voice sounds different from the main agent

The disclaimer uses a separate voice configuration. Check Channels > Voice > Agent Voice — the Disclaimer section has its own voice selection and tuning, independent of the main agent voice.

Deployment and version issues

Changes work in Sandbox but not in Live

You need to publish your changes and then promote them through your environments (Sandbox → Pre-release → Live). Changes in Draft or Sandbox are not automatically applied to Live.

See Environments and versions for the full promotion flow.

I promoted but the old behavior persists

1. Wait a few minutes — promotion can take a short time to propagate.
2. Check that you promoted the correct version by comparing version numbers in the Environments page.
3. If using a phone number to test, confirm the number is assigned to the correct environment.

Call drops after the disclaimer

If there are no knowledge base topics published to the Live environment, the agent has nothing to say after the disclaimer and will end the call. Ensure at least one topic is published and promoted before going live.

Function and flow issues

Function isn't being called by the agent

1. Check that the function is referenced in a topic’s Actions field or a step’s function list using @function_name.
2. Verify the function description is clear — the LLM uses it to decide when to call the function.
3. Check for typos in the function name reference.
4. Use conv.log statements to confirm whether the function is being reached at all.

Flow skips a step or transitions incorrectly

Check the goto_step calls in your flow functions. A common bug is using multiple if statements instead of if/elif/else, which causes later transitions to overwrite earlier ones. See Flow fundamentals for the correct pattern.

Function returns an error

1. Add conv.log statements to trace execution.
2. Check the function’s parameters match what the LLM is passing.
3. If calling an external API, verify secrets are configured for the correct environment.
4. Review the conversation in Conversations with the Function calls diagnosis toggle enabled.

See Function maintenance for detailed debugging steps.

Telephony and call routing issues

Call isn't being forwarded to the agent

1. Verify the forwarding number is correct and includes the country code.
2. Check that call forwarding is enabled with your telephone provider.
3. Ensure the transfer number is not part of the same ring group as the mainline number, which can create a loop.

Call transfers fail or drop

1. Check that the transfer number includes the country code (starts with +).
2. For SIP transfers, verify the URI and any custom headers.
3. Test in Sandbox first before promoting to Live.
4. If using Twilio, confirm the fallback number is configured correctly.

See Routing and handoffs for step-by-step guidance.

Caller's phone number shows incorrectly

Some telephone providers mask the caller number during forwarding, replacing it with the restaurant or business number. Contact your telephone provider and ask them to pass the caller’s real number through instead of overwriting it.

Additional troubleshooting resources

For more specific issues, see:

• Performance monitoring — latency, ASR, and quality issues
• Function maintenance — debugging function errors
• Voice and audio updates — audio quality and pronunciation
• Version management — deployment and rollback issues
• Smart Analyst — analyze patterns across hundreds of conversations to identify root causes

When to escalate

Contact PolyAI support when:

• You see repeated 4XX/5XX errors in call logs that persist after retrying
• SIP handoffs fail consistently and you’ve validated the number, URI, and headers
• Dashboards or transcripts aren’t loading at all
• Call volume drops more than 30% unexpectedly
• The agent’s error rate exceeds 5% across conversations
• You need changes beyond what’s available in the UI

Maintain a brief changelog of changes — it makes debugging faster when issues arise later.