Return selected tool-execution exceptions to the model as error ToolMessages.
on_error is called for each exception raised by tool execution. Return content
(a str or a list of content blocks) to convert the exception into a
ToolMessage(status="error"); return None — or simply don't return — to let the
exception propagate (halting the run). Handling is therefore opt-in — exceptions you
do not return content for propagate unchanged, so arbitrary internal exceptions are
never serialized to the model or end user unless you choose to surface them.
Langgraph control-flow signals (interrupts, parent commands) always propagate and
never reach on_error.
Prefer returning content that names the exception type over the raw exception message,
which may carry sensitive or internal detail.
Provide at least one of on_error or aon_error. aon_error handles errors on the
async execution path (falling back to on_error when omitted); the sync path only
ever calls on_error. For async-only usage, pass aon_error alone — running such a
middleware on the sync path raises, since the async handler cannot be awaited there.
This middleware does not retry. For retries, compose with ToolRetryMiddleware
placed inner and configured with on_failure="error" so exceptions reach this
middleware.
This middleware only sees exceptions raised by tool execution. Argument-binding
and validation errors are handled upstream by ToolNode (converted to an error
ToolMessage before the tool runs), so they do not reach on_error.
