langchain · difficulty ◆◆◆
ToolErrorMiddleware: Centralised, Configurable Tool Error Handling
One error policy for every tool in your agent
Your agent code was drowning in try/except blocks around every tool.
$ pip install -U langchain>=1.3.14What it does
ToolErrorMiddleware is a new LangChain middleware component (introduced in langchain 1.3.14, PR #38781) that intercepts errors raised by tools during agent execution and gives a structured, configurable hook to handle them. Instead of a raw Exception bubbling up and crashing the run, the middleware catches it, wraps it in a structured response, and optionally retries or falls back to a default value.
Why it matters
In production, tools fail for all sorts of reasons: network timeouts, rate limits, invalid inputs, missing permissions. Before this you had to wrap every tool call in manual error handling, making code verbose and inconsistent. ToolErrorMiddleware centralises the policy: configure it once at the agent level and every tool gets consistent, predictable error behaviour, keeping a single failure from crashing a long multi-step run.
Example
$ Configure ToolErrorMiddleware with a default value and max retries on a tool-calling agent.Tool call failed. Please try again or rephrase.When all retries are exhausted the agent receives default_value and continues its reasoning chain instead of crashing.
Common flags
- ToolErrorMiddleware
- Intercepts and processes all tool errors structurally
- ToolRetryMiddleware
- Retries tools on retryable exceptions (1.3.14, #38845)
- create_tool_calling_agent
- Accepts an error_handler kwarg
- RunnableConfig
- Carries middleware metadata like {"middleware": ["ToolErrorMiddleware"]}
History
Origin
Tool error handling was scattered across every tool and agent loop, forcing try/except boilerplate everywhere.
The fix
PR #38781 introduced ToolErrorMiddleware, letting developers centralise retry, fallback, and logging at the middleware layer.
Fun facts
Pros & cons
pros
- + Centralised error policy
- + Consistent fallback behaviour
- + No try/except in every tool
cons
- − New middleware, needs upgrade
- − Policy tuning required
Takeaways
- 1Configure error policy once
- 2Retry recoverable errors first
- 3Fall back to a default value