Tool Error Handling
LangChain gives you three mechanisms for tool error handling: ToolNode's built-in handle_tool_errors for LangGraph workflows, ToolException for per-tool control, and @wrap_tool_call middleware for cross-cutting production concerns. Knowing which to use — and how to write error messages the model can act on — is what separates a demo from a production agent.
Quick Reference
- →ToolNode(tools, handle_tool_errors=True) — simplest path: one flag, works in any LangGraph workflow
- →raise ToolException('message') inside a tool — per-tool control, no middleware needed
- →@wrap_tool_call middleware — production approach: intercept all tools, add retry, logging, security
- →Always set tool_call_id in the ToolMessage — the model needs it to match response to request
- →Error messages must be actionable: tell the model what failed, what to try next
- →Retry only idempotent operations — never auto-retry writes, sends, or payments
- →Keep error messages short: every token in an error ToolMessage costs context budget
- →Log tool failures to a separate metric, not just the agent trace — you need per-tool dashboards
Should You Handle This Error?
Not every tool error should be caught. Some errors signal that the agent should stop immediately — retrying or recovering would be wrong. Others are transient and fully recoverable. The first engineering decision is classification, not implementation.
| Error Type | Examples | Response |
|---|---|---|
| Config / auth failure | Missing API key, invalid credentials | Crash fast — don't catch. The operator needs to fix this. |
| Bad agent input | Malformed query, out-of-range parameter | Return ToolMessage with correction guidance — model can retry. |
| Transient external failure | Timeout, 429 rate limit, 503 temporarily unavailable | Retry with backoff, then return ToolMessage if exhausted. |
| Resource not found | 404, empty result set | Return ToolMessage — model can try alternative tools or rephrase. |
| Tool logic bug | Unhandled exception in your code | Crash fast (or alert) — catching a bug silently makes it invisible. |
Wrapping all tool execution in a generic except Exception handler means logic errors in your tool code become silent ToolMessages. The agent limps along returning degraded answers. Distinguish between errors you own (crash) and errors from dependencies (recover).