Error handlers, node timeouts, and the recursion limit
A failed node attempt goes to its RetryPolicy and then to its error_handler, a timeout counts as one failure, and the recursion limit stops an endless run.
A node calls a service that fails, and you want the graph to try again and then go on to a report. Another node waits on a service that never answers. A third loop never meets its stop condition. LangGraph has one setting for each of these, and they act in a fixed order.
When you finish this section, you can give a node a retry policy, an error handler, and a timeout. You can also predict its attempts and set a fitting recursion limit.
RetryPolicy, then the error handler
RetryPolicy: the settings for running a failed node again: max_attempts, the wait between attempts, and retry_on, which decides which exceptions to retry.
Error handler: a function that runs after the last failed attempt of a node. It gets the state and a NodeError, and it returns an update or a Command.
The kit node flaky raises ValueError on every attempt. It has a policy of 3 attempts that retries ValueError, and a handler that goes to report:
def handler(state, error: NodeError):
return Command(update={"status": f"recovered from {error.node}: {error.error}"}, goto="report")
g = StateGraph(S)
g.add_node("flaky", flaky, retry_policy=RetryPolicy(max_attempts=3, initial_interval=0.0, jitter=False, retry_on=ValueError), error_handler=handler)compile adds a node named __error_handler__flaky for the handler. The run made three attempts, then the handler ran, and the graph finished:
{
"status": "recovered from flaky: upstream failed on try 3",
"attempts": 3
}
tries:
[
1,
2,
3
]max_attempts counts the first attempt. The fault tolerance page states the order: the retry policy decides first, and the handler runs only when no attempt is left. set_node_defaults(error_handler=...) on the StateGraph gives every node the same handler. In the kit, a node that raised KeyError went to it, and the run ended with default handler: KeyError in boom.
The default retry_on does not retry ValueError
A RetryPolicy() with no arguments makes 3 attempts, waits 0.5 s before the second, doubles each wait up to 128 s, and adds jitter. Its retry_on is default_retry_on. That function retries ConnectionError and HTTP status errors from 500 to 599 from httpx and requests. A requests.HTTPError with no response is retried too. It does not retry ValueError, TypeError, ArithmeticError, ImportError, LookupError, NameError, SyntaxError, RuntimeError, ReferenceError, StopIteration, StopAsyncIteration, or another OSError. It retries every other exception.
The kit gave flaky a policy of 2 attempts with the default retry_on. The node ran once, and the run raised:
raised builtins.ValueError: upstream failed on try 1
tries:
[
1
]So a policy that you add for a flaky service does nothing for a parse error, and that is often what you want. KeyError is a LookupError, so it is not retried either. Name the exception types in retry_on when you want them retried.
A retry runs the whole node again. The fault tolerance page says that the writes of a failed attempt are dropped, and that a side effect inside the node is not. Send an idempotency key with each side effect. Section 1.1 shows what such a key did in the crash lab.
Node timeouts
Node timeout: the timeout of add_node, in seconds, for each attempt of an async node. When an attempt runs longer, it fails with NodeTimeoutError.
The kit node slow sleeps 2 s, with a timeout of 0.05 s. ainvoke raised:
raised langgraph.errors.NodeTimeoutError: Node 'slow' exceeded its run timeout of 0.050s (elapsed: <seconds>).A timeout is one failed attempt, so the retry policy and then the error handler see it. With a handler, the same node gave the state NodeTimeoutError: Node 'slow' exceeded its run timeout of 0.050s (elapsed: <seconds>). in status, and the run went on. Figure 6.14 draws the path of a failure.
A timeout applies only to async nodes. The code refuses a timeout on a sync node, because a sync Python function cannot be stopped from outside. The kit does not record that refusal yet. A capture of it comes in the next edition, with the other open items of section 8.8.
The recursion limit
Recursion limit: the number of steps after which a run raises GraphRecursionError. Each step of the Pregel loop counts once, whatever number of nodes run in it.
A loop with recursion_limit=5 in the config raised after five steps:
raised langgraph.errors.GraphRecursionError: Recursion limit of 5 reached without hitting a stop condition. You can increase the limit by setting the `recursion_limit` config key.
For troubleshooting, visit: https://docs.langchain.com/oss/python/langgraph/errors/GRAPH_RECURSION_LIMITThree numbers are the default limit in different places, and they are easy to mix up:
| Where | Default | What sets it |
|---|---|---|
a compiled StateGraph | 10007 | DEFAULT_RECURSION_LIMIT in langgraph, or the variable LANGGRAPH_DEFAULT_RECURSION_LIMIT |
a create_agent graph | 9999 | the config that create_agent binds to its graph |
a langchain-core runnable config | 25 | DEFAULT_RECURSION_LIMIT in langchain_core |
The graph API page gives 10,007 since langgraph 1.1.4, and 10,000 between 1.0.6 and 1.1.3. Older advice names 25 as the graph default. At the pin, 25 is the default of a langchain_core runnable config, and a graph does not use it. Pass recursion_limit at the top level of the config, not under configurable. This manual records the different numbers as conflict D105, and section 8.1 shows the limit of Agent Server.
We measured each default of a plain loop on the Mac, one run of each case, with no model. A plain loop stopped at 10007 steps. With the variable set to 25, or with recursion_limit=25, it stopped at 25. Raw runs
The agent ran with Qwen3 4B on the x86 server guest, told to call a tool until the tool answered finished, which it never did. With recursion_limit=25, the agent made 13 model calls (Qwen3 4B, x86 server guest, 3 of 3). It made 51 at recursion_limit 101. With no limit, the lab script stopped it at 1200 s, after 121 model calls. Figure 6.15 shows each run.
So each turn of an agent is two steps, one in model and one in tools. Parallel tool calls from one model turn run as tasks of the same tools step. An agent that needs n sequential rounds of tool calls and one answer needs at least 2n + 1 steps.
RemainingSteps
RemainingSteps: a managed value that you declare as a key of the state. LangGraph fills it with the number of steps left before the limit, and a node or an edge can read it.
The kit loop routes to END when remaining_steps is 2 or less. With recursion_limit=5, the run stopped by itself with n at 3 and raised nothing. Use it to end a long run with a partial answer instead of an exception.
LangChain (Python): langchain, langchain-core, langgraph, deepagents, langsmith 1.5.0 · c2f4036 · 2026-11-11 · Edition 2026.11