# Handle Tool Errors in a LangGraph Agent

Yes. An agent gives the ToolNode an error handler that tells bad arguments, outages and missing keys apart, tests each path with no API key and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-tool-error-handling/langgraph/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads how tools are run before it changes how they fail. In a LangGraph project like langchain-ai/react-agent, `src/react_agent/graph.py` registers `ToolNode(TOOLS)` with no other argument, and `TOOLS` in `tools.py` holds one function, `search`, which builds `TavilySearch(max_results=runtime.context.max_search_results)` inside the call and awaits it. `uv.lock` pins `langgraph` 1.2.17 with `langgraph-prebuilt` 1.1.0, and in that version the node's default `handle_tool_errors` does one thing: an error in the arguments the model sent comes back to the model as a `ToolMessage`, and every other exception is raised again.

It then reproduces the three failures in the sandbox, with a scripted fake model so nothing outside is called. Arguments the tool does not accept, `{"q": ...}` for `{"query": ...}`, give the model a message that ends `query: Field required` and asks it to try again, which is the behaviour to keep. A search that raises, a timeout or a reset connection, raises straight out of `graph.ainvoke`: the caller gets a traceback and the turn is gone. The third is the quiet one. With no `TAVILY_API_KEY`, `TavilySearch(...)` fails validation inside the tool, the node files that under bad arguments, and the model is told `Error invoking tool 'search'` with an empty reason and `Please fix the error and try again`. It cannot fix a missing key. A model that follows the instruction calls the search again until the step limit, and the user reads that no answer could be found in the allowed steps.

The change is a handler, not a blanket catch. Setting `handle_tool_errors=True` would stop the crash, but the text it writes for a timeout is `Error: TimeoutError(...)` followed by `Please fix your mistakes`, which blames the model for an outage and invites the same retry. The agent writes a function in `tools.py` and passes it to the node. For an argument error it returns the node's own message unchanged. For anything raised while searching it returns a sentence that says the search is unavailable, not to call it again in this turn, and to answer from what is known while saying so. A missing key is treated as what it is, a deployment mistake: `search` catches the construction failure and raises a named `SearchNotConfiguredError`, and the handler raises it again so the run stops with a message an operator can act on.

Tests go in `tests/unit_tests/` beside the existing ones and are marked `pytest.mark.anyio`, with the backend fixed in `tests/conftest.py`. They replace `load_chat_model` with a scripted fake and `TavilySearch` with stubs that raise. Four cases: bad arguments produce a `ToolMessage` with `status` `error` and the field name; a raising search produces the unavailable message and the graph goes on to a final answer; an unset key raises `SearchNotConfiguredError` out of `ainvoke`; and a model that keeps asking for the tool ends with the step-limit message and not an exception. The agent runs `uv sync --extra dev`, since `ruff` and `mypy` are in the `dev` extra and not the dependency group, then `ruff check .`, `mypy --strict src/` and `pytest tests/unit_tests`, as `.github/workflows/unit-tests.yml` does.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Make tool failures in this LangGraph agent predictable. Read pyproject.toml, uv.lock (langgraph and langgraph-prebuilt versions), every file under src/react_agent, tests/conftest.py, both test directories, the Makefile and .github/workflows first, and read the installed ToolNode source for what handle_tool_errors does by default. Reproduce three failures with a scripted fake model and no API key, and quote what each does today: the model sends arguments the search tool does not accept; the search raises a timeout or connection error; TAVILY_API_KEY is not set. Then pass ToolNode a handler function defined in src/react_agent/tools.py: for an argument error return the node's own message unchanged so the model can correct itself; for any error raised while searching return a ToolMessage text saying the search is unavailable, not to retry it in this turn, and to answer from what is known while saying so; for a missing key make search raise a named SearchNotConfiguredError and have the handler re-raise it so the run fails with a clear message. Do not use handle_tool_errors=True, and say in the pull request what message it would have produced. Add unit tests under tests/unit_tests for the three paths plus one where the model keeps calling the tool until the recursion limit, using stubs in place of TavilySearch and load_chat_model. Run uv sync --extra dev, ruff check ., mypy --strict src/ and pytest tests/unit_tests, do not run tests/integration_tests, paste the output in the pull request and open it.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

A pull request that touches two source files and adds one test file. `tools.py` gains the exception class, the handler and a few lines around the `TavilySearch` construction; `graph.py` changes one line, the `ToolNode` call. The description opens with a table of the three failures, each with the message or traceback it produced before and what it produces now, taken from the agent's own reproduction and not from the library's documentation.

A reviewer reads the sentence the model receives when the search is down, because it is a prompt: it decides whether your agent admits it could not search or answers with confidence from stale knowledge. They check that the handler's catch is narrow enough, so that a bug in a future tool surfaces as an exception in logs and not as a polite message the model works around. And they try the missing-key path once in the real deployment, since the unit test proves the exception is raised and cannot prove your process reports it where someone is looking.

## Run it on every agent error alert

Tool failures show up in production as a rise in failed or apologetic runs. In the console, add an automation on the Project that holds the agent's repository with a `webhook` trigger and a prompt that says: the alert below reports failing agent runs; find the tool involved, reproduce the failure with a stub, give it the same handling the search tool has, add a test and open a pull request. The alert's body, up to 64 KB, is placed after the prompt as the event. A Grafana contact point can call the trigger's URL itself, because it can send the `Authorization: Bearer <secret>` header the trigger requires. A service that only signs its own requests cannot, so for that one a small handler on your server receives its webhook and forwards the body with the header.

## Why run it on Rush?

This is a bug that hides from the person who wrote the agent. On a laptop the key is set and the network is fine, so the search never fails and the default behaviour is never seen. The agent's sandbox has no `TAVILY_API_KEY` unless you saved one as a Project secret, which is exactly the condition that produces the silent retry loop, and it can make the search raise on demand. Each failure is run, its output is kept in the session's transcript, and the before column of the pull request's table is a quote from that transcript.

It also needs no credentials to do properly. The model is a script and the search is a stub, so the run spends nothing at a search provider and cannot leak a key into a log. When an alert starts it at night, the work happens in the background with nobody at a keyboard, and what waits in the morning is a pull request with a reproduction, a fix and passing checks, ready for the one decision that is yours: what the agent should tell a user when its tool is down.

## Frequently asked questions

### What does ToolNode do with an exception by default?

In `langgraph-prebuilt` 1.1.0 it turns an error in the arguments the model sent into a `ToolMessage` so the model can correct the call, and raises everything else. A network error inside a tool therefore ends `graph.invoke` with that exception unless you pass `handle_tool_errors`.

### Why not just set handle_tool_errors=True?

It catches every exception and tells the model to fix its mistakes, whatever went wrong. For a timeout that message is false and prompts the same call again; for a missing key it hides a deployment problem behind a conversation. A handler function lets each kind of failure get the response that fits it.

### Will the agent add retries with backoff?

Not unless you ask. This page's request keeps the change to classification: the model is told the search is unavailable and moves on. If you want one retry before that, say so in the prompt and name the limit; the test for it uses a stub that fails once and then succeeds.

## More LangGraph jobs

- [Trim Message History in a LangGraph Agent](https://getrush.ai/run/trim-message-history/langgraph/)
- [Upgrade Python Dependencies Weekly for a LangGraph Agent](https://getrush.ai/run/upgrade-python-dependencies/langgraph/)
- [Write pytest Tests for a LangGraph Agent](https://getrush.ai/run/write-pytest-tests/langgraph/)

## More jobs like this: Fix a bug from an alert

- [Make a Stripe Webhook Handler Idempotent](https://getrush.ai/run/add-webhook-idempotency/stripe/)
- [Fix "The 'ansible.builtin.include' action plugin has been removed" in an Ansible playbook](https://getrush.ai/run/fix-ansible-include-action-removed/ansible/)
- [Fix "apt-key: not found" and "apt-key is deprecated" in a Dockerfile](https://getrush.ai/run/fix-apt-key-not-found/docker/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
