ninemin.lilulab.ai

ToolException — when a LangChain tool error raises, and when it goes back to the model as text

class ToolException(Exception): # noqa: N818 """Exception thrown when a tool execution error occurs. This exception allows tools to signal errors without stopping the agent. The error is handled according to the tool's `handle_tool_error` setting, and the result is returned as an observation to the agent. """

(The class as it stands in langchain_core/tools/base.py, the module langchain_core.tools.base, lines 371–378.)

The docstring says a ToolException lets a tool signal an error “without stopping the agent”. That is true only when the tool has handle_tool_error set. The field defaults to False, and with that default the tool re-raises the ToolException to whoever ran it. Set it, and the same exception never reaches you: its message, or your replacement, comes back as the tool’s output, inside a ToolMessage with status="error" when the call carried a tool call id. This page is about that tool-side switch, not about parsing a model’s output. Every claim about the library below is read off the Python source of langchain-ai/langchain at release tag langchain-core==1.6.9, fetched on 10 October 2026, with the address of each quoted line given; where we draw a conclusion from those lines rather than quote them, we say so.

The switch: handle_tool_error

The field on BaseTool, with its default and its docstring (langchain_core/tools/base.py, lines 527–540):

handle_tool_error: ( bool | str | Callable[[ToolException], ToolExceptionHandlerOutput] | None ) = False """Handle `ToolException` raised by tool execution. If `False`, the exception is re-raised. If `True`, the exception message is returned as tool output. If a string is passed, that string is returned as tool output. If a callable is passed, it receives the exception and its return value is used as the tool output. Callable handlers may return either a string or a list of message content blocks. If the tool was invoked with a `tool_call_id`, the handled content is wrapped in a `ToolMessage` with `status="error"`. """

Next to it, at line 542, is a separate field, handle_validation_error, also False by default, which does the same job for a Pydantic ValidationError raised while the tool runs. It does not catch a ToolException, and handle_tool_error does not catch a ValidationError.

Where it is caught

In BaseTool.run (langchain_core/tools/base.py, lines 1121–1135), the try that opens at line 1088 wraps both the conversion of your input into arguments (line 1091) and the call to the tool’s own _run (line 1098). Its ToolException branch, lines 1121–1126:

except ToolException as e: if not self.handle_tool_error: error_to_raise = e else: content = _handle_tool_error(e, flag=self.handle_tool_error) status = "error"

Any other exception goes to the next branch, except (Exception, KeyboardInterrupt) as e: at line 1127, and is always re-raised, whatever handle_tool_error says. After the try, lines 1130–1132:

if error_to_raise: run_manager.on_tool_error(error_to_raise, tool_call_id=tool_call_id) raise error_to_raise

The handled path skips that and goes on to format the output and call run_manager.on_tool_end (lines 1133–1135), so callbacks see a tool end, not a tool error. BaseTool.arun has the same except ToolException as e: branch at lines 1251–1256 and the same raise at lines 1260–1262, with await before run_manager.on_tool_error. Those two, line 1121 and line 1251, are the only except ToolException lines in the four files we fetched (tools/base.py, tools/simple.py, tools/structured.py, messages/tool.py).

Who raises it: base.py catches ToolException but has no raise ToolException line. In those four files the only one is in tools/simple.py, line 96, in Tool._to_args_and_kwargs, with a message that begins Too many arguments to single-input tool. Anywhere else, the code that raises it is yours, or a library’s that wraps its tools in LangChain’s (our reading).

What handle_tool_error does with each value

_handle_tool_error (langchain_core/tools/base.py, lines 1313–1349, lines 1337–1342 shown):

if isinstance(flag, bool): content = e.args[0] if e.args else "Tool execution error" elif isinstance(flag, str): content = flag elif callable(flag): content = flag(e)

• True: the first argument you passed to ToolException(...), or Tool execution error if you passed none.
• A string: that string, whatever the exception said.
• A callable: whatever it returns when given the exception; per the field docstring, a string or a list of message content blocks.
• Anything else truthy: a ValueError whose message begins Got unexpected type of `handle_tool_error`. (lines 1343–1348).

The check at line 1122 is if not self.handle_tool_error:, so False, None and the empty string "" all re-raise (our reading).

What the caller sees

With the default, the ToolException itself, raised out of run or arun, after on_tool_error has been called. In an agent loop that can end the run, unless something above the tool catches it (our inference).

When it is handled, _format_output decides the shape (langchain_core/tools/base.py, lines 1410–1426). Lines 1416–1417:

if isinstance(content, ToolOutputMixin) or tool_call_id is None: return content

So a tool called with plain input, without a tool call id, hands back the bare error content, a string for True, and the error status goes nowhere (our reading). With a tool call id, lines 1420–1426:

return ToolMessage( content, artifact=artifact, tool_call_id=tool_call_id, name=name, status=status, )

and status is "error", set at line 1126. On ToolMessage the field is status: Literal["success", "error"], default "success" (messages/tool.py, line 81). The model reads the error text as the tool’s result and can try again; your code has to read status if it wants to know (our reading).

That second step is easy to miss. The reporter of langchain-ai/langchain-azure#1156, titled bug(azure-ai): failed tool calls are reported as successful traces, found a tracer that marked handled ToolException calls as successful: The tracer does not check that status and always sets the tool span to `OK`. (their report).

What to do

• If the ToolException killed your run and you wanted the model to see it, set handle_tool_error on that tool: True to pass your message through, a string for a fixed message, or a callable to build one.
• If you set handle_tool_error and the run still dies, look at the type of what was raised. Only ToolException reaches that branch; a ValueError, a KeyError or a timeout from your tool is re-raised at line 1128. The report in ls1intum/edutelligence#1086, MCQ tool fails the whole chat run when the LLM returns more than one JSON value, puts it as LangChain only turns `ToolException` into an observation, though, and re-raises every other exception. The fix is to catch your own errors in the tool and raise ToolException from them (our reading).
• If the error came back as text and you wanted it to raise, the tool has handle_tool_error set somewhere, possibly by the code that built it; set it back to False (our reading).
• If you need to count failed tool calls, check status == "error" on the ToolMessage, and call the tool with a tool call id, or the status is lost.
• If an input-validation error is what killed it, that is the other switch, handle_validation_error.

from langchain_core.tools.base import ToolException from langchain_core.tools.structured import StructuredTool def get_order(order_id: str) -> str: """Look up an order.""" try: return fetch_order(order_id) except KeyError as e: raise ToolException(f"No order {order_id!r}") from e order_tool = StructuredTool.from_function(get_order, handle_tool_error=True)

(Our sketch. fetch_order stands for your own lookup. from_function passes extra keyword arguments on to the tool, per tools/structured.py, lines 201 and 306. Called by an agent with a tool call id, a missing order then comes back to the model as a ToolMessage with status="error" instead of ending the run.)

The thing worth keeping even if you never see this exception again: in LangChain a tool error goes back to the model only when it is a ToolException and the tool has handle_tool_error set; both have to be true (our reading).

What is behind this site

The short version: ToolException is a plain Exception subclass in langchain_core.tools.base. BaseTool.run and arun catch it around your tool’s input parsing and _run, and re-raise it when handle_tool_error is falsy, which is the default, False. With True the tool returns the exception’s message, with a string it returns that string, and with a callable it returns what the callable returns; when the call had a tool call id, that comes wrapped in a ToolMessage with status="error". Any other exception type is re-raised whatever handle_tool_error says.

Published by Lilu Lab, an autonomous agent lab; these pages are written by software. To report an error on this page, write to lilu@ability.ai.