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

> Common variable and tool-testing issues

## Common Issues

### Variable not showing in dropdown

* **Cause:** Variable comes from a node that doesn’t run before the current node.
* **Fix:** Check flow order; the variable must be created by a predecessor node (or be system/custom).

### "Variable not found"

* **Cause:** Typo in name or variable was removed.
* **Fix:** Check spelling and that the variable still exists in the right scope.

### JSONPath extraction returns null

* **Cause:** Path doesn’t match the actual (or expected) response.
* **Fix (API):** Run **Test Tool**, inspect response, use path selector on that response, check preview. Consider optional/missing fields.
* **Fix (Web):** Ensure expected response matches real web tool output; test manually; use path selector on expected structure; check object vs string.

### Tool test fails or returns error

* **Cause:** Bad config, auth, or API problem.
* **Fix:** Check URL, method, headers, body; verify credentials; read error in test response; test the API directly (e.g. Postman).

### Path selector empty or wrong

* **API:** Ensure **Test Tool** succeeded and response is 2xx and JSON (not HTML).
* **Web:** Provide expected response; ensure it’s valid JSON if object; confirm format (object vs string).

### Works in test, fails in production

* **Cause:** Production response shape differs from test.
* **Fix:** Test with production-like data; handle optional/missing fields; add error handling; test success and error shapes.

### Can’t select path in path selector

* **Cause:** Invalid or very complex response.
* **Fix:** Validate JSON; simplify if possible; try manual JSONPath or extract a parent and use static variables to parse.

### AI extraction not working

* **Cause:** Prompt too vague.
* **Fix:** Make the extraction prompt specific and add examples.

### DTMF variable conflicts with transitions

* **Cause:** DTMF capture on number keys while transitions use same keys.
* **Fix:** Turn off number-key transitions or use different DTMF keys for capture vs transitions.

### Static variable shows wrong value

* **Cause:** Referenced variables not available or have wrong values.
* **Fix:** Check that referenced variables exist and are in scope; check defaults.

### Slow with many variables

* **Cause:** Too many variables or heavy nested structures.
* **Fix:** Remove unused variables; simplify structures.

### Variable not available in single prompt agent

* **Cause:** Using extracted or static variables, which single prompt agents don’t support.
* **Fix:** Single prompt agents support only **system** and **custom** variables. If you need extraction or flow logic, use a Flow Builder agent.

### Custom variable not showing in single prompt agent

* **Cause:** Variable not defined in the Variables Panel.
* **Fix:** Open the Variables Panel, add the custom variable with name and default value. It will be available as `{{variable_name}}` in the prompt and stored as `params` in the configuration.

### Single prompt agent needs to extract data

* **Cause:** Single prompt agents don’t support variable extraction from conversations or tools.
* **Fix:** Use a Flow Builder agent and conversation/tool nodes with AI or toolpath extraction. Single prompt agents are intended for simple Q\&A without extraction.

## Tool Testing

**"Test Tool" disabled or not working:** Finish required fields (URL, method, auth).

**Test slow or timeout:** Check endpoint and network; increase timeout if possible; try a simpler endpoint.

**Test returns HTML instead of JSON:** Wrong URL or auth; verify endpoint and headers; test in browser/Postman.

**Works in test, not in production:** Use realistic test data; handle null/optional fields; add error handling.

**Web tool – unknown response format:** Run the web tool manually; inspect console/returned data; document format and use as expected response.

**Web tool – different format than expected:** Update expected response; reconfigure extraction; re-test path selector; consider string vs object.

**String vs object for web tool:**

* **String:** One piece of data, simple text (e.g. `"Order #12345 confirmed"`).
* **Object:** Multiple fields, structured data (e.g. `{"order_id": "12345", "status": "confirmed", "total": 99.99}`).

**Path selector and string response:** For string responses use `$` (entire string). Don’t use nested paths on strings; use object format or extract full string and parse in static variables if needed.

See [Extracted Variables](./extracted-variables), [Best Practices](./best-practices), and [Examples](./examples) for more context.