Skip to main content
Most issues fall into a handful of patterns. Before you open a support ticket, run through the checks below.
Faster route for many of these: open the failing conversation, then ask Wren to fix it — “the agent told the caller we offer same-day delivery; we don’t, update the shipping topic”. See Iterate after a call for the full loop.

​
Quick reference

​
Knowledge base issues

Diagnosis steps:
  1. Open the conversation in Conversations and enable Topic citations in the Diagnosis toggle group on the Transcription tab.
  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
Diagnosis steps:
  1. Check that the topic is on the Branch you are testing. If you are testing in Live, check that the Branch has been published.
  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 on a Branch in Sandbox but hasn’t been published to Live
  • Sample questions are too few or too narrow
  • Topic name is not semantically related to the user’s query
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

The change may be pulling from cached audio. Go to Voice > Audio library, find the specific audio clip, update the speed setting, and regenerate the audio.
Use the Pronunciation section in Voice > Advanced settings > Speech. You can provide IPA notation, SSML overrides, or regex-based corrections. See Audio Management for details.
The disclaimer uses a separate voice configuration. Check Voice > Settings – the Disclaimer section has its own voice selection and tuning, independent of the main agent voice.

​
Deployment and version issues

You need to publish your Branch to Live from the Publish menu. Changes on a Branch in Sandbox are not applied to Live until you publish them.See Environments for the full publishing flow.
  1. Wait a few minutes. Publishing can take a short time to propagate.
  2. Check that the right change reached Live. Open Live history on the Deployments page and confirm the newest version is yours.
  3. If using a phone number to test, confirm the number is assigned to the correct environment.
If there are no knowledge 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 to Live before going live.

​
Function and flow issues

  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.
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.
  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 Tool calls diagnosis toggle enabled.
See Function maintenance for detailed debugging steps.

​
Telephony and call routing issues

  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.
  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 publishing to Live.
  4. If using Twilio, confirm the fallback number is configured correctly.
See Routing and handoffs for step-by-step guidance.
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:

​
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.
Last modified on September 15, 2026