6.8

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:

pythona node with a retry policy and an error handlerFull log
    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:

jsonthree attempts, then the handlerFull log
{
  "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:

outputa ValueError with the default retry_onFull log
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:

outputan async node past its timeoutFull log
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.

Fig. 6.14the path of a failed node attemptdecision
The path of a failed node attempt A decision figure. A node attempt raises, or runs past its timeout and fails with NodeTimeoutError. The first check is retry_on with attempts left: yes runs the node again, as flaky did for tries 1 to 3 with retry_on ValueError. With no attempt left, or an exception that retry_on refuses, the next check is an error_handler. With a handler, the node __error_handler__flaky runs and its Command goes to report. With no handler, invoke raises, as ValueError upstream failed on try 1 did with the default retry_on. a node attempt fails an exception, or NodeTimeoutError timeout slow, 0.05 s retry_on matches, attempts left? RetryPolicy of the node yes: run again flaky, tries 1 to 3 error_handler set? on the node or by set_node_defaults no ValueError with the default retry_on __error_handler__flaky Command(goto='report') yes invoke raises ValueError: upstream failed on try 1 no report status: recovered from flaky The run goes on only on the left path. The right path ends the run.
Every failed attempt, a timeout too, goes to retry_on first, and the error handler runs only after the last attempt, or the run raises. Read from the failed attempt at the top. Each grey box is one check, with the outcome of the kit beside its arrow. The rose box is the error that leaves invoke.

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:

outputa loop past its recursion limitFull log
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_LIMIT

Three numbers are the default limit in different places, and they are easy to mix up:

WhereDefaultWhat sets it
a compiled StateGraph10007DEFAULT_RECURSION_LIMIT in langgraph, or the variable LANGGRAPH_DEFAULT_RECURSION_LIMIT
a create_agent graph9999the config that create_agent binds to its graph
a langchain-core runnable config25DEFAULT_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.

Fig. 6.15steps before GraphRecursionErrorchart
Steps before GraphRecursionError A dot chart on a log scale of the steps each run made before it stopped. A StateGraph loop on the Mac, with no model, stopped at 25 steps with recursion_limit 25 and with the environment variable set to 25, and at 10007 with no config. A create_agent agent with Qwen3 4B on the x86 server guest stopped at 25 steps after 13 model calls and at 101 after 51, in 3 of 3 runs each. With the default limit, the lab script stopped it at 242 steps after 121 model calls in 21 minutes. 10 100 1k 10k steps before the stop, log scale 25 config 25 25 env var 25 10007 default 25 config 25 13 calls 101 config 101 51 calls 242 default 121 calls StateGraph loop, the Mac create_agent, Qwen3 4B Calls under an agent case are its model calls. The agent ran on the x86 server guest. The rose default run did not reach the limit: the lab script stopped it after 1260 s.
A plain graph stops at 10007 steps, and each agent step is one model call or one tool call, so 25 steps allow 13 model calls. Read one dot for each case, on a log scale. The graph runs are from the Mac and the agent runs from Qwen3 4B on the x86 server guest. The label names the case and its model calls.

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