Skip to main content
Find the symptom you see, then check the causes in the order listed: the most common comes first. Each answer links to the page that explains the feature. For any call, the transcript and logs in call details are the best place to start, and for flow agents Debug mode steps through the call on its flow.

What the agent says

The agent reads out braces or variable names

The variable is written with single braces, such as {customer_name}. Only double braces are variables, so single braces are passed on as written: a Static message speaks them, and the model sees them in a prompt. Write {{customer_name}}, or type {{ and pick the variable from the list. See Variables.

A variable comes out empty (“Hello ,“)

See Pass values when a call starts and Jinja syntax.

Parts of my prompt are missing, or the agent says both sides of an if

When a template has an error, the call goes on with every Jinja tag removed: the text from every branch stays and every {{ }} value is gone. For the comparison, write:
Open the Jinja2 template editor, check the status line for the error, and preview with test data shaped like your real calls. See What happens on a template error.

The agent reads out symbols, lists or formatting

To catch it on calls, a guardrail can check the agent’s reply with the built-in hasMarkdown check. See Write a prompt that works on calls.

The agent speaks the wrong language or dialect

See Voice, language and dialect.

The agent mispronounces a word

The transcript keeps the agent’s original word; only the speech changes. See Pronunciation dictionaries.

The agent says an ID instead of its name

{{ agent_name }} holds the agent’s ID on calls. Write the agent’s name into the prompt and greeting as text. See Write a prompt that works on calls.

Dates and times are wrong

See Dates and times.

How the agent listens and talks

The agent cuts callers off mid-sentence

Callers reading out a number in pieces, or pausing to think, are taken as finished. Turn on Enhanced turn taking, or raise Response delay in steps of 100 ms. See Turn taking and interruptions.

Callers can’t interrupt the agent

Background noise stops the agent or is taken as speech

Raise Minimum interruption duration or VAD activation threshold, or turn on noise cancellation. See Call behavior settings.

Replies feel slow

The Conversation log flags calls with Slow replies (over 1.5 seconds on average), and call details split each reply time into speech to text, model and speech. See Call details.

The agent never hangs up

See End the call.

Calls end on their own

Flow agents

My router path is never taken

See Router step.

The call stays in a step and never moves on

See Transitions.

The agent takes the wrong path

The model picks a prompt transition by its When to take this path text, next to every global step’s trigger condition, with no order. Describe what the caller says or wants, not what the agent does next, and make each description clearly different from the others and from your global steps. Hide paths that don’t make sense yet with Offer it only when. See Design flows that hold up on real calls.

Keypad digits aren’t saved

See Keypad input.

A key press does nothing

A transfer doesn’t happen in a browser test

A browser test has no phone line to transfer. Test transfers on a phone call. See Transfer call step.

Variables and values

A condition on a number or yes or no value never matches

Every value reaches the call as text. A number you send as 5 is the text "5", and comparing text with a number fails. Convert with | int. A JSON true you send, or a yes or no value the agent extracted, reads True, while the text "true" stays "true": compare with the exact text that arrives. See Every value is a string.

A value I pass when the call starts is ignored

See Which value wins when names clash.

A system variable has the wrong value

A dynamic, extracted or local variable with a system variable’s name, such as current_date, replaces the system value for the rest of the call. Rename your variable. See System variables.

Tools

A tool works in the test but fails on calls

See Connect an API.

A tool call times out

A request fails after the tool’s Timeout, 5 seconds by default. Raise it, up to 60 seconds, on the tool or in the agent’s Tool configuration. In a flow, the step then takes On Failure. See Timeouts.

The agent never uses my tool, or ignores its result

A web tool always fails

See Web tools.

Knowledge base

A knowledge base item isn’t used

See How the agent searches on a call.

I can’t add knowledge base items

Add free text and Add document are disabled when your storage is full. Delete items you no longer need, or move to a plan with more storage. A file is refused when it isn’t a supported type or is over 21 MB. Website (URL) items can’t be added. See Add to the knowledge base.

An item shows a failed status

Hold the pointer over the status to see the reason after “Failure reason:”. For Upload failed and Reading failed, check that the file opens and add it again. For Ingestion failed, open Review chunks and click Index to try again. See Statuses.

Phone calls

Calls don’t reach my agent

See Phone numbers and Bring your own number.

Inbound calls work but outbound and batch calls fail

The SIP address or trunk credentials are wrong. Inbound calls can still work with wrong values, so only dialing out fails. SIP numbers can’t be edited: delete the number and add it again with the right values, then place a test call. See Bring your own number.

Callers hear an old version

See Environments and releases.

Calls changed without a publish

Phone numbers, environment values in prod, and the policies, guardrails and functions on an agent are not part of a version. Changing them reaches calls right away. See What a version holds.

My changes aren’t saved, or my draft looks different

See Your draft.

Batch calls

My batch call doesn’t call anyone

See When calls go out.

A batch call stays In progress

A recipient has a timezone value Hamsa doesn’t recognize. That recipient is never called, so the batch call never finishes. Use IANA names such as Asia/Riyadh, not abbreviations like GST. See Time zones.

Saving a batch call fails with “Reserved concurrency exceeds your voice agent concurrency limit”

This batch call’s concurrency plus that of every Scheduled, In progress and Paused batch call must fit in your plan’s limit. Lower this one’s concurrency, wait for one to finish, or cancel one. See Concurrency.

Some recipients are never called again

Only Failed calls are retried automatically, up to 3 attempts in all. No answer is final until you retry the batch call yourself. See Retries.

Rows in my file are rejected

Phone numbers must be digits only, with a leading + or 00 and a country code, and appear once in the file. In Excel, format the phone number column as text so the + stays. See Phone number rules.

Webhooks

My webhook isn’t called

See Webhooks.

Publishing fails with “Webhook URL is not reachable”

On a single prompt agent, Hamsa checks that the webhook URL answers when you publish. If it doesn’t answer within 2 seconds, publishing stops. Make sure the endpoint is up and reachable from the internet, then publish again.

My server rejects the webhook’s token

Hamsa sends Authorization: Bearer <token>. You can enter the token with or without the word Bearer: Hamsa adds it only when it’s missing. Check that the token is the one your server expects, with no extra spaces. See Set up a webhook.

Editing, testing and publishing

Test is disabled, or a test call won’t start

See Test your agent.

I can’t publish

See Drafts and versions.

”This agent is open for editing in another tab”

You can edit an agent in one tab at a time. Click Use here to edit in this one.

My draft is gone

A draft expires after 7 days without an edit. If you discarded it, open the ⋯ menu and click Bring back within 30 days. To start again from a published version, open it and click Copy to draft. See Your draft.

I can’t delete a tool, knowledge base item or rule

Tools, knowledge base items, policies, guardrails, functions and macros can’t be deleted while an agent uses them. Remove them from each agent first. The app names the agents that use a knowledge base item.

Safety

A guardrail pattern never matches

See Write checks that match.

Website and API

The widget doesn’t appear or the microphone doesn’t work

Visitors talk to what prod runs, so publish changes before you check them on your site. The widget can’t pass variables; use the web SDK for that. See Embed on your website.

API requests are refused

See API keys.

Limits

Every number you can run into.

Call details

Transcript, logs and Debug mode for one call.

Test your agent

Reproduce a problem on your draft.

Design flows that hold up

Avoid the common flow problems.