When a tool fails

When an operation fails with on_error: "abort" (the default), the tool stops and the model is handed an error result. The model then writes what the agent says next, so what the caller hears is decided by the agent’s prompt. This page covers what the model is told, every way an operation fails, and where to find out what happened. For on_error itself, see the operation tree.

What the model is told

Error result	Cause
`Sorry, I wasn't able to complete that just now.`	An operation failed with `on_error: "abort"`, or a referenced secret no longer exists
`Tool arguments are invalid at <path>: <message>`	The model’s arguments did not match `json_schema`. The tree never ran
`Sorry, I can't complete that action after an interruption.`	A `disable_interruptions` tool was called while the agent was already being interrupted

A model with no instruction for a failure improvises, and “you’re all set for Thursday” is a plausible improvisation. Write the failure case into the prompt for every tool that matters, saying what the agent must not claim and where it can go instead:

- If book_appointment fails, say the booking did not go through, do not give a
  time or reference, and offer to transfer the caller to the front desk.
- If lookup_order fails, say you cannot reach the order system right now. Never
  guess a status or a delivery date.

A tool that ends the call or hands off tells the model nothing, failed or not.

A failure handled by on_error: "continue" leaves no record on a live call: no tool.failed webhook and no failed tool card, because the tool as a whole succeeded. Only a test run shows it. Use continue only on operations you do not need to hear about.

Operation errors

Error	Cause and fix
`HTTP request failed with status <code>`	The endpoint returned 400 or more. No retries. A test run shows the response body
`HTTP operation returned a non-JSON response`	Usually an HTML error or login page. A test run shows the body
`HTTP response exceeds 1048576 bytes`	The response is over 1 MB
`publish field path '<path>' was not found in operation output`	The path is wrong, the API omitted the key this time, or the URL redirected: redirects are not followed, so the result was `{}`. See http
`destination <ip> is not allowed (private/internal)`	The host resolves to a non-public address. See network rules
`could not resolve host '<host>'`	DNS failed
`the '<name>' header resolved to a value an HTTP header cannot carry`	A templated header became non-ASCII or contained a line break
A timeout (`ReadTimeout`, `ConnectTimeout`, …)	The operation’s `timeout` elapsed. For a slow endpoint use `long_running_task`, not a longer timeout
`code operation failed: <message>`	The script threw, ran out of memory, or exceeded its timeout (`execution exceeded <n>ms`). The last ten `console` lines are appended
`gt` needs two numbers, and cannot compare …	An `if` compared a value that is not a number, often one an earlier `continue`d operation never published. See conditionals
`the spoken line did not finish playing within 60s`	A `wait_for_playback` line stalled
`transfer is only available on phone calls`	A `transfer` ran on a web or text conversation
`frontend_rpc …`	See frontend RPC
`secret '<NAME>' is not a workspace secret and was not supplied for this session`	The tool aborts before any operation runs, regardless of `on_error`. Session start refuses a missing name for the agents it plans, so this means a session with no request (inbound) or a handoff target outside the plan reads a secret only a session can supply, or a workspace secret was deleted after a rollback
`<kind> reads {{secrets.<NAME>}}, but only an http or code operation may use a secret`	A tool version saved before secrets were limited to http and code; that operation fails under its own `on_error` instead of speaking or storing the value

Background tool failures

A long_running_task tool that has already handed the turn back still reports its failure: the error becomes the tool’s result, the agent tells the caller, tool.failed fires, and the tool card on the call turns red. A failure inside the first second is reported in the same turn, like any tool. A background tool is cancelled when the call ends or the agent hands off, leaving its side effects half applied, with no warning. Work that must complete belongs behind a webhook and your own queue.

Where to look

The call's transcript

Each tool call shows the arguments the model chose and what came back. A failed call is marked failed with its error, “The model was told” shows the exact result the model got, and a badge flags required arguments the model sent empty — fix that in the tool’s description, not the tree. See calls.

The call's events

tool.started and tool.ended carry timing and outcome; on a background tool tool.ended has background: true and tool.reply says whether the agent voiced the result. tool.step_limit_reached means the agent wanted more tool calls in one turn than allowed.

A test run

Reproduce the failure with POST /v1/tools/{tool_id}/run: every step’s resolved request, response, published values and error_type. See testing and publishing.

Webhooks

tool.invoked carries the tool name and arguments; tool.failed carries the error, for an aborted tree or arguments that did not match the schema. See webhooks.

console output from a code operation is not visible on a live call except as the ten lines appended to a failure. Debug scripts in a test run.

Symptom to cause

Symptom	Usual cause
The agent apologised and moved on	An operation aborted; check the tool card
The agent confirmed something that never happened	No prompt rule for the failure, or a background tool cancelled by the call ending
A tool did half its work, with no error anywhere	An operation with `on_error: "continue"` failed; run the tool to see it
A path you know exists stopped publishing	The URL now redirects, or the API omits the key in this case
A tool fix changed nothing on live calls	The agent still pins the old version; publish the agent. See the pin rule
A required argument arrived as `""`	The model called the tool before it had the value; tighten the description

Debugging agents

The wider playbook for odd, slow or silent agents.

Testing and publishing

Reproduce a failure against the draft.

Get started

Build

Guides

When a tool fails

What the model is told

Operation errors

Background tool failures

Where to look

Symptom to cause

Next

Debugging agents

Testing and publishing

​What the model is told

​Operation errors

​Background tool failures

​Where to look

​Symptom to cause

​Next

Debugging agents

Testing and publishing

What the model is told

Operation errors

Background tool failures

Where to look

Symptom to cause

Next