langchain · difficulty ◆◆◆
ToolErrorMiddleware: Intercept and Transform Tool Errors via on_error
Log, transform, and recover from tool failures in one place
You had no single place to log and transform every tool failure.
$ pip install -U langchain langchain-openaiWhat it does
ToolErrorMiddleware is a middleware component in LangChain v1.3.13 (released alongside langchain 1.3.14) that intercepts tool errors and processes them in a structured way before they propagate up the call chain. It sits beside ToolRetryMiddleware and gives developers a hook to handle, log, or transform tool errors at the infrastructure level, without touching individual tool implementations.
Why it matters
Tool failures are not exceptional in production LLM apps; they are expected. Network timeouts, rate limits, malformed API responses, and permission errors happen routinely. Before ToolErrorMiddleware these required try/except blocks inside every tool or agent loop. Now you centralise error handling in the middleware layer, making code cleaner, more consistent, and easier to test.
Example
$ Wrap a flaky search tool with a middleware whose on_error logs and returns a fallback.[ERROR] Tool ‘search’ failed: Search API timeout\ncontent=‘The search failed, but here is a fallback response.’The on_error callback can re-raise, return a fallback, or record to observability.
Common flags
- ToolRetryMiddleware
- Retries tools that throw retryable exceptions (1.3.12)
- ToolErrorMiddleware
- New in 1.3.13; intercepts and processes all tool errors via callback
- init_chat_model
- New meta extra support added in 1.3.13
- ChatOpenAI
- OpenAI chat model; explicit prompt caching in 1.3.5
History
Origin
Error handling was scattered across tool and agent implementations, making it inconsistent and hard to test.
The change
ToolErrorMiddleware (PR #38781) added an on_error callback hook so logging, transformation, and fallback live at the infrastructure level.
Fun facts
Pros & cons
pros
- + Single observability hook
- + Cleaner business logic
- + Easy to test
cons
- − Callback shape is new
- − Requires an upgrade
Takeaways
- 1Centralise error handling in middleware
- 2Log and transform in on_error
- 3Chain with ToolRetryMiddleware