Skip to main content

​
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, Best Practices, and Examples for more context.