> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryhamsa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting Hamsa Agents

> Fixes for common problems by symptom: the agent reads out braces, a router path is never taken, calls miss the agent, a webhook or knowledge item goes unused.

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](https://docs.tryhamsa.com/agents/monitor/call-details.md) are the best place to start, and for flow agents [**Debug mode**](https://docs.tryhamsa.com/agents/monitor/debug-mode.md) 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](https://docs.tryhamsa.com/agents/variables/overview.md#where-you-can-use-variables).

### A variable comes out empty ("Hello ,")

| Cause | Fix |
| - | - |
| Nothing sent a value, and the variable has no default. A missing variable renders as empty and the call goes on. | Give the dynamic variable a default, send it in `params`, or add a fallback such as `{{ customer_name or "there" }}`, which covers a missing and an empty value. |
| The name you send differs from the name in the prompt. Names are case sensitive, and a batch call column is used exactly as written. | Use the same snake\_case name everywhere. |
| In a batch call, you used `{{name}}`. The `name` column isn't passed to the agent. | Put the name in another column too, such as `customer_name`. |
| A flow step reads a value that hasn't been collected yet on this path. | Check in **Debug mode** which step sets it, or add a fallback. |

See [Pass values when a call starts](https://docs.tryhamsa.com/agents/variables/dynamic-variables.md) and [Jinja syntax](https://docs.tryhamsa.com/agents/variables/jinja.md#when-a-variable-has-no-value).

### 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.

| Cause | Fix |
| - | - |
| A number comparison on text, such as `{% if visits > 2 %}`. Every value is text. | Convert the value with the `int` filter first (see below). |
| A typo in a filter name, or a filter that doesn't exist. | Check the spelling against the supported filters. |
| A missing `{% endif %}` or `{% endfor %}`. | Close every block. |
| Handlebars or other syntax, such as `{{#if}}`, or two pipes for "or". | Use Jinja: `{% if %}` and `or`. |

For the comparison, write:

```jinja theme={null}
{% if visits | int > 2 %}A regular caller.{% endif %}
```

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](https://docs.tryhamsa.com/agents/variables/jinja.md#what-happens-on-a-template-error).

### The agent reads out symbols, lists or formatting

| Cause | Fix |
| - | - |
| **Prompt enhancer** is set to **Disabled**, so nothing tells the model to write plain spoken text. | Set it to **Basic** or **Advanced**, or say in your prompt to reply in plain spoken sentences with no formatting. |
| Your prompt asks for bullet points, tables or Markdown. | Ask for short spoken sentences instead. |

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](https://docs.tryhamsa.com/agents/build/write-a-prompt.md#what-the-prompt-enhancer-adds).

### The agent speaks the wrong language or dialect

| Cause | Fix |
| - | - |
| The voice is in another dialect. The agent speaks the dialect of its voice. | Pick a voice in your callers' dialect. |
| **Prompt enhancer** is **Disabled**, so no dialect instruction is added. | Turn the enhancer on, or name the language and dialect in your prompt. |
| **Language/dialect switcher** is on, and the model switched because it judged the caller wanted it. | Turn the switcher off if the agent should keep one dialect. |
| The prompt and examples are written in another language. | Write example phrases in the language and dialect the agent speaks. |

See [Voice, language and dialect](https://docs.tryhamsa.com/agents/settings/voice-and-language.md).

### The agent mispronounces a word

| Cause | Fix |
| - | - |
| The word isn't in a pronunciation dictionary on the agent. | Add it to a dictionary and turn the dictionary on for the agent. |
| The agent writes the word with different capitals. Matching respects letter case. | Add each spelling, such as "Hamsa" and "HAMSA". |
| The word has a letter attached, such as وجوجل for جوجل. Only whole words match. | Add the attached form as its own entry. |

The transcript keeps the agent's original word; only the speech changes. See [Pronunciation dictionaries](https://docs.tryhamsa.com/agents/voices/dictionaries.md).

### 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](https://docs.tryhamsa.com/agents/build/write-a-prompt.md#structure-that-works).

### Dates and times are wrong

| Cause | Fix |
| - | - |
| **Timezone** is left on **Default (UTC)**. Calls then use the platform's default time zone. | Set **Timezone** in **Call settings** to your business's time zone. |
| `{{ current_time }}` in the prompt was filled in when the call started. | For "what time is it now", rely on the date and time the model gets every turn. |
| A condition compares `current_time` as a number. It's a sentence. | Use `current_weekday` or `current_date`, or compare in a tool. |

See [Dates and times](https://docs.tryhamsa.com/agents/build/write-a-prompt.md#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](https://docs.tryhamsa.com/agents/settings/call-behavior.md#turn-taking-and-interruptions).

### Callers can't interrupt the agent

| Cause | Fix |
| - | - |
| **Interrupt** is off in **Call settings**. | Turn it on. |
| On a flow agent, the step isn't a Conversation step, or its **Interruption** is **Disable**. Only Conversation steps and the Start step's opening message can be interrupted. | Set the step's **Interruption** to **Inherit** or **Enable**, and keep messages on other steps short. |
| The agent is saying the greeting, the message at the maximum call length, or the smart call end goodbye. These can't be interrupted. | Keep them short. |
| The caller speaks for less than **Minimum interruption duration**. | Lower it, down to 0.2 seconds. |

### 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](https://docs.tryhamsa.com/agents/settings/call-behavior.md#noise-cancellation).

### Replies feel slow

| Cause | Fix |
| - | - |
| **Response delay** is high. | Lower it in steps of 100 ms. |
| The model is slow to start speaking. | Compare **responds in** in the model list and test a faster model. |
| The agent waits for a knowledge base search (up to 2 seconds a turn), or searches before answering with **Agentic RAG** on. | Attach only the items the agent needs. Turn on **Thinking voice** so the caller hears typing while the agent works. |
| A flow step waits for a live variable (up to 1.5 seconds). | Use a **Variable on node exit** for values only one step needs. |

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](https://docs.tryhamsa.com/agents/monitor/call-details.md).

### The agent never hangs up

| Cause | Fix |
| - | - |
| **Smart call end** is off on a single prompt agent. It then never hangs up on its own. | Turn it on and describe when to end in **Smart call end prompt**. |
| The flow has no path to an **End call** step. | Connect the last steps to an End call step, or turn on **Smart call end**. |
| The caller went quiet. The agent checks in after **User inactivity timeout** but never hangs up because of silence. | Set a sensible **Max call duration**. |

See [End the call](https://docs.tryhamsa.com/agents/settings/call-behavior.md#end-the-call).

### Calls end on their own

| Cause | Fix |
| - | - |
| The call reached **Max call duration**, 5 minutes for a new agent. | Raise it, up to 60 minutes. |
| A router found no matching path and its **Else** isn't connected. The agent says "No router path" and ends the call. | Connect **Else**. See [My router path is never taken](#my-router-path-is-never-taken). |
| **Smart call end** ended the call earlier than you wanted. | Make the **Smart call end prompt** more specific, for example "after the appointment is confirmed and the caller has no other questions". |
| A guardrail with **Disconnect** matched. | Check the call in [call details](https://docs.tryhamsa.com/agents/monitor/call-details.md) to see which guardrail fired, and run it in **Monitor** while you tune it. |
| A transfer at the maximum call length failed. | Check the number, and test on a phone call: transfers need a phone number on the agent. |

## Flow agents

### My router path is never taken

| Cause | Fix |
| - | - |
| An earlier path matched first. The router checks paths in the order you added them, oldest first, and the panel lists them newest at the top. | Make the conditions exclusive, so only one can match. |
| The path isn't connected to a step. Unconnected paths are skipped. | Drag from the path's handle to the next step. |
| **Equals** or **Contains** compares text, and capital letters count: `Gold` doesn't equal `gold`. | Match the exact text, or use **Matches regex**. |
| A yes or no value reads `True` or `False`, with a capital letter. | Compare with `True`, not `true`. |
| A number comparison reads a value that isn't a plain number, such as `$100` or "ten". The condition is false. | Save a plain number in the variable, for example with a **Check the value** rule. |
| The variable has no value yet when the call reaches the router. Every operator except **Exists** and **Does not exist** is then false. | Collect it earlier on the path, or add an **Exists** path. |

See [Router step](https://docs.tryhamsa.com/agents/flow/steps/router.md).

### The call stays in a step and never moves on

| Cause | Fix |
| - | - |
| The step has no way out: no **Prompt**, **DTMF input**, **After user replies**, live variable or **Auto** transition, and the flow has no global steps. | Add a transition, or end the step with **Auto**. |
| The transition isn't connected, or is turned off. | Connect it to the next step. |
| A required **Variable on node exit** has no valid value yet. The model keeps asking for it before it can take a prompt transition. | Make the variable optional if the flow can live without it. |
| A **Check the value** rule refuses what the caller says. | Loosen the rule, or tell the caller the format you need in the step's message. |
| An **Offer it only when** rule hides the transition. | Check the rule's variables in **Debug mode**. |
| The caller hasn't replied yet. A step's opening line can't take a transition; the call moves only in reply to the caller. | Use **Auto** when the step should move on after its message. |

See [Transitions](https://docs.tryhamsa.com/agents/flow/transitions.md).

### 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](https://docs.tryhamsa.com/agents/flow/design-tips.md).

### Keypad digits aren't saved

| Cause | Fix |
| - | - |
| The step has no **DTMF input** transition with `#` or `*`. Typed digits are saved only when the caller presses one. | Add the transition and connect it. |
| The caller didn't press the finishing key, so the digits were lost when the call left the step. | Say the key in the message: "Type your account number, then press hash." |

See [Keypad input](https://docs.tryhamsa.com/agents/flow/keypad-input.md).

### A key press does nothing

| Cause | Fix |
| - | - |
| The key has no **DTMF input** transition on the step the call is in. Keys only work on the current step. | Add a transition for that key on each step where callers may press it. |
| You expected the key to open a global step. Global steps are started by what the caller says, not by keys. | Add a **DTMF input** transition on each step instead. |
| DTMF capture is on for the step, so number keys go into the digits instead. | Turn capture off on steps where keys choose a path. |

### 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](https://docs.tryhamsa.com/agents/flow/steps/transfer-call.md#good-to-know).

## 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](https://docs.tryhamsa.com/agents/variables/jinja.md#every-value-is-a-string).

### A value I pass when the call starts is ignored

| Cause | Fix |
| - | - |
| The agent has an environment variable with the same name. The environment value wins over values passed at call start and over batch call columns. | Rename one of them. |
| The call ran another version or environment than you expected. | Check the version and environment on the call in the Conversation log. |

See [Which value wins when names clash](https://docs.tryhamsa.com/agents/variables/overview.md#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](https://docs.tryhamsa.com/agents/variables/system-variables.md).

## Tools

### A tool works in the test but fails on calls

| Cause | Fix |
| - | - |
| The test retried a failed request; calls don't retry. | Make the API answer reliably on the first try. |
| A secret was renamed or deleted. Tools that reference it send the request without the credential. | Update the tool's reference. Secret names are case sensitive. |
| The tool is in another version on the agent. Agents keep a tool's version until you sync. | Click **Sync to latest** on the agent's tool. |

See [Connect an API](https://docs.tryhamsa.com/agents/tools/api-tools.md).

### 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](https://docs.tryhamsa.com/agents/tools/api-tools.md#timeouts).

### The agent never uses my tool, or ignores its result

| Cause | Fix |
| - | - |
| The tool isn't selected for this agent. | Add it under **Tools** (single prompt) or in a **Tool** step (flow). |
| The description and prompt don't say when to use it. The model decides from them. | Name the tool and the moment in the prompt, for example "before you offer a time". |
| **Async execution** is on. A single prompt agent then never gets the result. | Turn async off for requests whose answer the caller needs. |
| On a flow agent, the response isn't shown to the model. | Extract the values you need into variables on the step and use them in the next Conversation step. |

### A web tool always fails

| Cause | Fix |
| - | - |
| The call is a phone call, or a test call from the app. Neither has a page that answers the tool. | Test web tools from your own page with the web SDK. |
| Your page answers under another name. Single prompt agents call the tool in lowercase, with other characters turned into `_`. | Name the tool in lowercase letters, digits and underscores, and use the same name on your page. |
| Your page takes longer than 15 seconds to reply, or doesn't reply with JSON. | Keep the handler fast and reply with JSON. |

See [Web tools](https://docs.tryhamsa.com/agents/tools/web-tools.md).

## Knowledge base

### A knowledge base item isn't used

| Cause | Fix |
| - | - |
| The item isn't **Completed**. At **Pending review** it isn't searchable and doesn't appear when you pick items for an agent. | Open **Review chunks** and click **Index**. |
| The item isn't attached to this agent. | Select it in the agent's **Knowledge base** section. |
| You edited chunks but didn't index again. Edits show "Changes not indexed" and reach the agent only after you index. | Click **Index**. |
| The caller's turn was very short or only filler words, which don't start a new search. | Expected. Earlier matches stay in memory for 3 turns. |
| The search took longer than 2 seconds, so the reply went ahead without it. | The result is added to the memory for the next turn. |
| With **Agentic RAG** on, the agent decided not to search. | Say in the prompt when to look things up, or turn **Agentic RAG** off to search on every turn. |
| The passage doesn't match closely. | Keep one topic per item, and check the chunks in **Review chunks**: fix chunks flagged **Too long** or **Possibly low value**. |

See [How the agent searches on a call](https://docs.tryhamsa.com/agents/knowledge-base/overview.md#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](https://docs.tryhamsa.com/agents/knowledge-base/add-items.md).

### 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](https://docs.tryhamsa.com/agents/knowledge-base/review-and-index.md#statuses).

## Phone calls

### Calls don't reach my agent

| Cause | Fix |
| - | - |
| The number has no agent. The call fails with "No voice agents assigned to this phone number." | Assign the number in the agent's **Phone number** section or on the number's page. |
| The number was moved to another agent. A number answers for one agent at a time. | Assign it back. |
| As many calls are running as your plan allows. The call is refused with "Voice agent concurrency limit reached. Please wait for an active call to finish." | Wait, end **Pending** calls you don't need in the Conversation log, or move to a plan with more concurrent calls. |
| The credit balance is at zero or below. | Add credits in [Billing](https://docs.tryhamsa.com/overview/billing.md). |
| Your SIP provider doesn't send the number's calls to the **Origination URI**, or, on the Hamsa SIP gateway, the **Carrier IPs** don't list the addresses it sends from. | Copy the values from the number's page to your provider again. If your provider or firewall only accepts known IPs, allow the gateway's IP, `34.243.238.8`, for SIP and for audio on UDP ports 16384 to 32767. See [The gateway's addresses](https://docs.tryhamsa.com/agents/connect/bring-your-own-number.md#the-gateways-addresses). |

See [Phone numbers](https://docs.tryhamsa.com/agents/connect/phone-numbers.md) and [Bring your own number](https://docs.tryhamsa.com/agents/connect/bring-your-own-number.md).

### 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](https://docs.tryhamsa.com/agents/connect/bring-your-own-number.md#good-to-know).

### Callers hear an old version

| Cause | Fix |
| - | - |
| Your changes are still in your draft. Callers only hear published versions. | Publish, or request a merge. |
| With deployments on, the version is in dev or staging. Callers on prod hear nothing new until it reaches prod. | Promote it to prod in **Releases**. |
| The number points at another environment. | Check **Releases** > **Channels**. |
| Prod runs an A/B test, and this caller gets the other version. The same caller keeps hearing the same version. | Check the A/B test in **Releases**. |

See [Environments and releases](https://docs.tryhamsa.com/agents/release/environments.md).

### 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](https://docs.tryhamsa.com/agents/release/drafts-and-versions.md#what-a-version-holds).

### My changes aren't saved, or my draft looks different

| The editor shows | Fix |
| - | - |
| "Not saved: the draft moved on" | Click **Reload**. Your changes are kept on this device, and the editor offers them back after the reload. |
| **Unresolved conflict** · **Review** | Your draft was saved from another tab or the API while you edited here. Click **Review** and choose what to keep. |
| "Not saved yet" | You have restored unsaved changes. Click **Keep** or **Discard**. |
| Your draft shows a newer version than the one you started from | You hadn't edited it yet, so it moved onto the newest version on its own. |
| "Your draft expired \{when}, after 7 days without an edit." | Click **Bring back**. |

See [Your draft](https://docs.tryhamsa.com/agents/release/drafts-and-versions.md#your-draft).

## Batch calls

### My batch call doesn't call anyone

| Cause | Fix |
| - | - |
| Today isn't one of the **Days of week**, or the time is outside the **Time range**. Recipients wait for the next window. | Check the window in the batch call's **Timezone**. |
| It was created with **Send now**, which uses Asia/Amman (UTC+3) for the window. | Choose **Schedule** and set the **Timezone** for your recipients. |
| The scheduled start is read in your computer's time zone, not the **Timezone** you picked. | Check the start against your own clock. |
| It is **Paused**. | Resume it. |

See [When calls go out](https://docs.tryhamsa.com/agents/connect/batch-calls.md#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](https://docs.tryhamsa.com/agents/connect/batch-call-file.md#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](https://docs.tryhamsa.com/agents/connect/batch-calls.md#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](https://docs.tryhamsa.com/agents/connect/batch-calls.md#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](https://docs.tryhamsa.com/agents/connect/batch-call-file.md#phone-number-rules).

## Webhooks

### My webhook isn't called

| Cause | Fix |
| - | - |
| The webhook was changed in your draft but not published. | Publish, so calls pick up the webhook. |
| Your endpoint was down or took longer than 30 seconds. There are no retries, so that event is lost. | Answer with `200` at once and do slow work after you reply. Compare with the Conversation log now and then. |
| Your server uses a self-signed TLS certificate. Hamsa checks the certificate. | Use a certificate from a trusted authority. |
| You expected an event at the start of the call. Events are sent only when a call ends, plus `no_answer` and `error` for outbound calls. | Use `call_end`. |
| The call couldn't be saved. `call_end` is sent only after the call is saved. | Check the call in the Conversation log. |
| The URL doesn't start with `https://`. | Use an HTTPS endpoint. |

See [Webhooks](https://docs.tryhamsa.com/agents/connect/webhooks.md#delivery).

### 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](https://docs.tryhamsa.com/agents/connect/webhooks.md#set-up-a-webhook).

## Editing, testing and publishing

### Test is disabled, or a test call won't start

| Cause | Fix |
| - | - |
| The editor has unsaved changes ("Please save changes before testing"). | Wait for the draft to save. |
| The agent uses dynamic variables. Every one needs a value in the dialog before the call starts. | Fill in each value. |
| You are viewing a version that runs in more than one environment. | Choose one under **Choose whose values to test with**. |
| The browser blocks the microphone. | Allow it for the site in your browser, and for your browser in your computer's settings. |
| For a phone call test, the agent has no phone number. | Assign a number first. |

See [Test your agent](https://docs.tryhamsa.com/agents/release/test-your-agent.md).

### I can't publish

| Message | Fix |
| - | - |
| "Fix the errors in this agent before publishing it." | Fix the issues the editor lists. |
| "Nothing new to publish: the draft matches \{version}." | Make a change first. |
| "Going live needs the Deploy permission. Your edits are saved in the draft." | Request a merge, or ask an Owner or Admin. |
| "Webhook URL is not reachable" | See [above](#publishing-fails-with-webhook-url-is-not-reachable). |
| A banner says the model needs your key. | Pick an API key secret under the model, or switch to a model without the **Your key** tag. |

See [Drafts and versions](https://docs.tryhamsa.com/agents/release/drafts-and-versions.md#publish-a-version).

### "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](https://docs.tryhamsa.com/agents/release/drafts-and-versions.md#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

| Cause | Fix |
| - | - |
| The pattern has capital letters. Checks read a lowercase copy of the text. | Write patterns in lowercase. |
| The pattern uses named groups, written `(?<name>…)`. These don't work on calls. | Use plain groups. |
| The guardrail is switched off, or not added to this agent. | Add it to the agent and turn it on. |
| The check ran out of time. All checks on one piece of speech share half a second. | Keep checks and functions fast. |

See [Write checks that match](https://docs.tryhamsa.com/agents/safety/policies-and-guardrails.md#write-checks-that-match).

## Website and API

### The widget doesn't appear or the microphone doesn't work

| Cause | Fix |
| - | - |
| Your site isn't served over HTTPS. Browsers only allow the microphone on secure pages. | Serve the site over HTTPS. |
| Your site's Content Security Policy blocks the widget. | Allow scripts from `assets.tryhamsa.com` and frames from `agents.tryhamsa.com`. |
| The snippet was typed by hand or copied from another agent. | Copy it again from the agent's publish page. |

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](https://docs.tryhamsa.com/agents/publishing/embed.md).

### API requests are refused

| Status | Message | Fix |
| - | - | - |
| 401 | "Bearer token Authorization header is deprecated!" | Send `Authorization: Token <key>`. |
| 403 | "A secret key cannot be used from a browser. Keep it on your server; use a public key in pages and apps." | Call from your server, or use a public key in the page. |
| 403 | "A public key can only mint call tokens (POST /v1/voice-agents/call-token)." | Use a secret key on your server for anything else. |
| 401 | "This API key value was rotated and no longer works. Use the new value." | Use the new value. |
| 402 | "Balance is insufficient, please renew or upgrade your plan!" | Add credits. |

See [API keys](https://docs.tryhamsa.com/overview/create-api-keys.md#when-a-request-is-refused).

## Related

> [card] [Limits](https://docs.tryhamsa.com/agents/reference/limits.md)
>
> Every number you can run into.

> [card] [Call details](https://docs.tryhamsa.com/agents/monitor/call-details.md)
>
> Transcript, logs and Debug mode for one call.

> [card] [Test your agent](https://docs.tryhamsa.com/agents/release/test-your-agent.md)
>
> Reproduce a problem on your draft.

> [card] [Design flows that hold up](https://docs.tryhamsa.com/agents/flow/design-tips.md)
>
> Avoid the common flow problems.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.