Error Recovery: What an Agent Should Do When a Tool Fails
An agent that crashes when a tool fails has thrown away the one capability that made it worth building. The model can read an error and try something else — but only if the error reaches it, in a form it can act on, with the retry decision already made by code. The tool result is the error channel The default instinct from ordinary software — let the exception propagate — is wrong here. A tool…
When a tool fails, an agent should not simply crash or propagate the exception. Instead, it should process the error, format it appropriately for the user, and then continue with the task. This approach is crucial for ensuring the agent's overall effectiveness. The three key elements of an effective error handling mechanism are: what failed, why it failed, and what the user should do next.
A well-structured error message contains all this information. For example, instead of simply saying "Error" or "KeyError: 'user_id'", a good error message might look like this: "ERROR FileNotFoundError: 'src/retry.py' does not exist. The workspace root contains: src/, tests/, README.md. Try list_dir('src') to see what is actually there." This message provides specific information about the failure, the current state of the workspace, and a practical step the user can take to resolve the issue.
Another good error message could be: "ERROR ValidationError: 'plan' must be one of basic|pro|scale; you sent 'Pro Plan'. Retry with the exact enum value." This message clearly states what went wrong, what the correct input should be, and provides a specific action for the user to take.
A particularly important error class is 'empty-result'. This occurs when a tool succeeds but finds no results. This might seem like a minor issue, but it can actually lead to infinite loops as the model tries to re-run the same query again. To handle 'empty-result' errors effectively, the tool should return the fact that was searched, how many items were in the candidate set before filtering, and one concrete way for the user to widen the search.
For instance, "0 of 1,284 open issues matched 'timeout'; this index does not correct spelling." This message not only informs the user about the failure, but also gives them actionable information to help them move forward.
The error handling process also involves differentiating between various types of errors. For instance, 'transient' errors are those that can be retried, such as 429, 502, 503, 504, connection reset, or timeout. These errors are handled by the code, not the model, and the model should usually never learn that they occurred. 'Malformed-args' errors are those where the schema is violated or the input is unparseable. These errors can often be fixed by the model in one step if provided with precise information about the error.
'Not-found' errors occur when a path, id, or record does not exist. While this is not a failure of the tool, it is a fact about the world that the user should be informed about. 'Forbidden' errors are those that result from policy refusal, budget exceedance, or sandbox denial. These errors should not be retried, and the model must be explicitly told to stop trying.
Lastly, 'corrupt-state' errors are the most serious, indicating a half-completed write, an open transaction, a locked file, or a repository conflict. In these cases, retrying or replanning is not safe, and the run should be halted and escalated to a human.
In conclusion, effective error recovery is a critical aspect of building robust tools. It involves catching errors, formatting them for the user, and providing clear and actionable instructions on what to do next. By implementing this approach, agents can maintain their functionality even when tools fail, thereby maximizing their worth.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.
