Skip to content
LgPy

LangGraph Advanced Error Handling and Recovery (Python)

Native RetryPolicy, TimeoutPolicy, node-level error_handler, dead-letter patterns, checkpoint-based resumption, and structured error types (NodeError, NodeTimeoutError, NodeCancelledError, GraphRecursionError, ErrorCode) — source-verified.

Verified against langgraph==1.2.22 (modules: langgraph.types, langgraph.graph.state, langgraph.runtime, langgraph.errors).

LangGraph handles errors in layers. This page covers what happens after a node fails: error handlers, dead-letter routing, resuming from a checkpoint, and the exception types. Retry, timeout and cache options are documented once, in Node policies.

LayerPrimitiveScope
Automatic retryRetryPolicy on add_nodeRe-runs a node on transient exceptions
Timeouttimeout= / TimeoutPolicy on add_node (async nodes)Cancels a hung attempt with NodeTimeoutError
Node error handlererror_handler= on add_nodeFallback once retries are exhausted
Graph-wide handlerset_node_defaults(error_handler=...)One fallback for every node
Dead-letter routingHandler returns Command(goto="dead_letter")Continue on a recovery path instead of failing
Checkpoint resumptiongraph.invoke(None, config)Re-run from the failed step after a fix
Agent-levelModelRetryMiddleware, ModelFallbackMiddleware, ToolRetryMiddleware, ToolErrorMiddlewarecreate_agent agents (Chapter 8)

Configure retries and timeouts as described in Node policies. Two points that matter for recovery:

  • The default retry_on retries most exceptions but not ValueError, TypeError, other programming errors, or OSError (including the built-in TimeoutError). It does retry LangGraph’s own NodeTimeoutError.
  • A retried node runs again from the start, so side effects must be idempotent.

Using ExecutionInfo for idempotent retries

Section titled “Using ExecutionInfo for idempotent retries”

When a node is retried, runtime.execution_info.node_attempt increments (1-indexed). Use this to issue idempotency keys so external APIs aren’t double-charged.

from langgraph.runtime import Runtime
from langgraph.types import RetryPolicy
import time
async def idempotent_payment_node(state: State, runtime: Runtime) -> dict:
info = runtime.execution_info
if info.node_attempt > 1:
elapsed = time.time() - (info.node_first_attempt_time or time.time())
print(f"Retry #{info.node_attempt} after {elapsed:.1f}s")
# task_id is stable across retries — safe idempotency key
result = await post_payment(
idempotency_key=info.task_id,
amount=state["amount"],
)
return {"result": result}
builder.add_node(
"payment",
idempotent_payment_node,
retry_policy=RetryPolicy(max_attempts=3, initial_interval=2.0),
)

An error handler runs when a node has failed and its retries are exhausted. Declare the failure parameter with the NodeError type (from langgraph.errors); LangGraph injects it by that annotation, so error: Exception does not work. NodeError has .node (the failed node’s name) and .error (the exception).

The handler’s return value decides what happens next:

  • A Command(update=..., goto="node") applies the update and continues at that node. Use this for dead-letter routing.
  • A plain dict applies the update and ends that branch: the failed node’s outgoing edges are not followed.
  • Raising fails the run.
import asyncio
from typing_extensions import TypedDict
from langgraph.graph import StateGraph, START, END
from langgraph.errors import NodeError
from langgraph.types import Command, RetryPolicy
class State(TypedDict, total=False):
query: str
result: str
error: str
async def fetch(state: State) -> dict:
raise ConnectionError("api.example.com unreachable") # fails on every attempt
async def process(state: State) -> dict:
return {"result": state["result"].upper()}
async def dead_letter(state: State) -> dict:
print(f"ALERT: {state['query']!r} dead-lettered: {state['error']}")
return {"result": "[fallback response]"}
async def to_dead_letter(state: State, error: NodeError) -> Command:
# Runs once retries are exhausted. A plain dict would end the branch here;
# a Command chooses where the run continues.
return Command(update={"error": f"{error.node}: {error.error!r}"}, goto="dead_letter")
graph = (
StateGraph(State)
.set_node_defaults(error_handler=to_dead_letter) # every node
.add_node("fetch", fetch, retry_policy=RetryPolicy(max_attempts=3, initial_interval=0.01))
.add_node("process", process)
.add_node("dead_letter", dead_letter)
.add_edge(START, "fetch")
.add_edge("fetch", "process")
.add_edge("process", END)
.add_edge("dead_letter", END)
.compile()
)
print(asyncio.run(graph.ainvoke({"query": "weather"})))
# ALERT: 'weather' dead-lettered: fetch: ConnectionError('api.example.com unreachable')
# {'query': 'weather', 'result': '[fallback response]', 'error': "fetch: ConnectionError('api.example.com unreachable')"}

Handlers do not catch failures from tasks that run in parallel with others in the same super-step (parallel branches or Send fan-out): the exception propagates and fails the run. In fan-out workers, catch exceptions inside the worker and write them to a state key with a list reducer (for example errors: Annotated[list, operator.add]).

If set_node_defaults(timeout=...) is also set, the handler gets the timeout too and must be async def.

With a checkpointer, a failed run leaves its last checkpoint behind, and the failed node is still pending. Fix the cause (or the state) and call invoke(None, config) to continue from that step; nodes that already finished do not run again.

from typing_extensions import TypedDict
from langgraph.graph import StateGraph, START, END
from langgraph.checkpoint.memory import InMemorySaver
class State(TypedDict, total=False):
query: str
fetched: str
result: str
calls = {"fetch": 0}
def fetch(state: State) -> dict:
calls["fetch"] += 1
return {"fetched": f"data for {state['query']}"}
def process(state: State) -> dict:
if state["query"] == "bad":
raise ValueError("cannot process 'bad'")
return {"result": state["fetched"].upper()}
graph = (
StateGraph(State)
.add_node("fetch", fetch)
.add_node("process", process)
.add_edge(START, "fetch")
.add_edge("fetch", "process")
.add_edge("process", END)
.compile(checkpointer=InMemorySaver())
)
config = {"configurable": {"thread_id": "resume-demo"}}
try:
graph.invoke({"query": "bad"}, config)
except ValueError as exc:
print("run failed:", exc)
snapshot = graph.get_state(config)
print(snapshot.next) # ('process',): the node that failed, still pending
print(snapshot.values) # {'query': 'bad', 'fetched': 'data for bad'}
# Fix the bad input, then resume with None: fetch does not run again.
graph.update_state(config, {"query": "good"})
print(graph.invoke(None, config)) # {'query': 'good', 'fetched': 'data for bad', 'result': 'DATA FOR BAD'}
print("fetch ran", calls["fetch"], "time(s)") # 1

The same applies after a process crash: on restart, invoke(None, config) with the thread’s config resumes from the last checkpoint written. How much work is redone depends on the durability mode.

4. Structured error types — catching and inspecting failures

Section titled “4. Structured error types — catching and inspecting failures”

LangGraph defines a hierarchy of typed exceptions in langgraph.errors. Knowing which type is raised lets you write targeted except blocks in error handlers, retry predicates, and observability callbacks.

NodeError — error handler context (source-verified)

Section titled “NodeError — error handler context (source-verified)”

NodeError is a frozen dataclass injected into any function registered as an error_handler=. It gives the handler structured access to what failed and where:

from langgraph.errors import NodeError # langgraph.errors, 1.2.22
# NodeError is a frozen dataclass with two fields:
# node: str — name of the failing node
# error: BaseException — the raw exception that was raised

Use it to write generic handlers that log structured context:

from typing_extensions import TypedDict
from langgraph.graph import StateGraph, START, END
from langgraph.errors import NodeError
import logging
logger = logging.getLogger(__name__)
class State(TypedDict):
data: str
status: str
def flaky_node(state: State) -> dict:
raise ValueError("upstream service unavailable")
def structured_error_handler(state: State, error: NodeError) -> dict:
"""NodeError.node and NodeError.error give full context without re-parsing."""
logger.error(
"node_failure",
extra={"node": error.node, "exc_type": type(error.error).__name__},
)
return {"status": f"error in '{error.node}': {error.error}"}
graph = (
StateGraph(State)
.add_node("flaky", flaky_node, error_handler=structured_error_handler)
.add_edge(START, "flaky")
.add_edge("flaky", END)
.compile()
)
result = graph.invoke({"data": "input", "status": ""})
print(result["status"]) # error in 'flaky': upstream service unavailable

NodeTimeoutError — which timeout fired and how long it ran (source-verified)

Section titled “NodeTimeoutError — which timeout fired and how long it ran (source-verified)”

When TimeoutPolicy cancels a node, LangGraph raises NodeTimeoutError (not the built-in TimeoutError — this is intentional so that RetryPolicy’s default retry_on treats it as retryable). Key attributes:

AttributeTypeMeaning
nodestrName of the timed-out node
kind"idle" | "run"Whether idle_timeout or run_timeout fired
timeoutfloatThe threshold that was exceeded (seconds)
elapsedfloatHow long the node actually ran (seconds)
run_timeoutfloat | NoneConfigured run_timeout at the time of failure
idle_timeoutfloat | NoneConfigured idle_timeout at the time of failure
import asyncio
from typing_extensions import TypedDict
from langgraph.graph import StateGraph, START, END
from langgraph.errors import NodeTimeoutError
from langgraph.types import RetryPolicy, TimeoutPolicy
class State(TypedDict):
data: str
result: str
RETRYABLE_KINDS = {"run"} # retry on run_timeout but not idle_timeout
def retry_on_run_timeout(exc: BaseException) -> bool:
if isinstance(exc, NodeTimeoutError):
return exc.kind in RETRYABLE_KINDS
# fall back to the default behaviour for non-timeout errors
from langgraph.types import default_retry_on
return default_retry_on(exc)
async def slow_search(state: State) -> dict:
await asyncio.sleep(60) # simulate a slow operation
return {"result": "done"}
graph = (
StateGraph(State)
.add_node(
"search",
slow_search,
timeout=TimeoutPolicy(run_timeout=5.0, idle_timeout=2.0),
retry_policy=RetryPolicy(
max_attempts=2,
retry_on=retry_on_run_timeout, # only retry hard run_timeout, not idle
),
)
.add_edge(START, "search")
.add_edge("search", END)
.compile()
)

NodeTimeoutError does not inherit from asyncio.TimeoutError or TimeoutError. If you have an except TimeoutError guard in your handler, it will not catch this exception — use except NodeTimeoutError explicitly.

NodeCancelledError — asyncio.CancelledError from user code (source-verified)

Section titled “NodeCancelledError — asyncio.CancelledError from user code (source-verified)”

asyncio.CancelledError is a BaseException, which the Pregel runner interprets as a framework-initiated cancellation signal (tearing down sibling tasks after a peer fails). When a node’s own body raises it, LangGraph converts it into NodeCancelledError so it surfaces as a proper node failure rather than silently succeeding:

# langgraph.errors — source-verified, 1.2.22
class NodeCancelledError(Exception):
node: str # the node whose body raised asyncio.CancelledError

Catch it in a retry_on predicate to decide whether cancellation should trigger a retry:

import asyncio
from typing_extensions import TypedDict
from langgraph.graph import StateGraph, START, END
from langgraph.errors import NodeCancelledError
from langgraph.types import RetryPolicy
class State(TypedDict):
data: str
result: str
def retry_policy_for_cancelled(exc: BaseException) -> bool:
"""Retry once if the node cancelled itself, but not on other errors."""
return isinstance(exc, NodeCancelledError)
async def might_cancel(state: State) -> dict:
# Simulate a node that may cancel itself due to an external signal
if state.get("data") == "cancel":
raise asyncio.CancelledError("external interrupt")
return {"result": "ok"}
graph = (
StateGraph(State)
.add_node(
"work",
might_cancel,
retry_policy=RetryPolicy(max_attempts=2, retry_on=retry_policy_for_cancelled),
)
.add_edge(START, "work")
.add_edge("work", END)
.compile()
)

GraphRecursionError — handling the recursion limit (source-verified)

Section titled “GraphRecursionError — handling the recursion limit (source-verified)”

GraphRecursionError is raised when the graph has exhausted the maximum number of steps (recursion_limit). In LangGraph 1.2.22 the default is 10007 (set via DEFAULT_RECURSION_LIMIT in langgraph._internal._config; override the baseline with the LANGGRAPH_DEFAULT_RECURSION_LIMIT environment variable). It inherits from the built-in RecursionError:

class GraphRecursionError(RecursionError):
pass # carries an ErrorCode.GRAPH_RECURSION_LIMIT message

Two ways to handle it. Both use this loop, which needs 30 steps to finish:

from typing_extensions import TypedDict
from langgraph.graph import StateGraph, START, END
from langgraph.checkpoint.memory import InMemorySaver
class LoopState(TypedDict):
count: int
def step(state: LoopState) -> dict:
return {"count": state["count"] + 1}
loop_builder = (
StateGraph(LoopState)
.add_node("step", step)
.add_edge(START, "step")
.add_conditional_edges("step", lambda s: END if s["count"] >= 30 else "step")
)

Option 1 — raise the limit for long workflows:

loop = loop_builder.compile()
result = loop.invoke({"count": 0}, {"recursion_limit": 100}) # the config is the second argument
print(result) # {'count': 30}

Option 2 — catch it at the call site and resume from the checkpoint:

from langgraph.errors import GraphRecursionError
loop = loop_builder.compile(checkpointer=InMemorySaver())
cfg = {"configurable": {"thread_id": "long-run-1"}, "recursion_limit": 25}
try:
result = loop.invoke({"count": 0}, cfg)
except GraphRecursionError:
# The checkpoint was saved up to the last successful step.
# Resume by passing None as input: the new limit applies to this invoke only.
result = loop.invoke(None, {**cfg, "recursion_limit": 50})
print(result) # {'count': 30}

ErrorCode — structured error taxonomy (source-verified)

Section titled “ErrorCode — structured error taxonomy (source-verified)”

ErrorCode is an Enum whose string value is embedded in LangGraph exception messages and troubleshooting URLs. It is NOT exposed as an attribute on exception instances — code like exc.error_code == ErrorCode.GRAPH_RECURSION_LIMIT will not work. Prefer catching concrete exception types (NodeTimeoutError, GraphRecursionError, etc.); use message-string inspection only as a fallback.

from langgraph.errors import ErrorCode
# ErrorCode members (source-verified, 1.2.22):
# ErrorCode.GRAPH_RECURSION_LIMIT — recursion_limit exceeded
# ErrorCode.INVALID_CONCURRENT_GRAPH_UPDATE — parallel nodes wrote to a channel accepting
# only one value per super-step (unannotated key
# or second Overwrite in the same super-step)
# ErrorCode.INVALID_GRAPH_NODE_RETURN_VALUE — node returned a non-dict / bad type
# ErrorCode.MULTIPLE_SUBGRAPHS — ambiguous subgraph routing
# ErrorCode.INVALID_CHAT_HISTORY — malformed message sequence

The code string is embedded in the exception message — inspect it via str(exc), not via an attribute:

try:
loop_builder.compile().invoke({"count": 0}, {"recursion_limit": 5})
except RecursionError as exc:
if "GRAPH_RECURSION_LIMIT" in str(exc):
print("Graph hit recursion limit — increase recursion_limit in config")
BaseException
└── Exception
├── NodeTimeoutError # run_timeout or idle_timeout exceeded
├── NodeCancelledError # node body raised asyncio.CancelledError
├── InvalidUpdateError # e.g. two writes to a key without a reducer
├── EmptyInputError # the graph received an empty input
├── TaskNotFound # executor cannot find a task (distributed mode)
├── RecursionError
│ └── GraphRecursionError # recursion_limit steps exhausted
└── GraphBubbleUp # control flow, not failures: don't catch these broadly
├── GraphInterrupt # interrupt() paused the run
│ └── NodeInterrupt (deprecated)
├── ParentCommand # Command(graph=Command.PARENT) travelling upwards
└── GraphDrained # RunControl.request_drain() stopped the run

NodeError (the error-handler argument) is a dataclass, not an exception. All of these live in langgraph.errors. A broad except Exception: inside a node also catches GraphInterrupt, which breaks interrupt(); re-raise GraphBubbleUp if you must catch everything.


Comparison: native policies vs external libraries

Section titled “Comparison: native policies vs external libraries”
ScenarioLangGraph nativeWhy prefer native
Retry on HTTP errorsRetryPolicy(retry_on=...)Integrated with the graph execution loop; works with checkpointers
Custom backoffRetryPolicy(initial_interval, backoff_factor, max_interval, jitter)No extra dependency; applies per attempt inside the graph loop
TimeoutTimeoutPolicy(run_timeout=..., idle_timeout=...)Cooperative cancellation via asyncio; heartbeat support
Global fallbackset_node_defaults(error_handler=...)One line; no decorator boilerplate per node
Resume after crashgraph.invoke(None, config)Requires checkpointer; saves/restores state automatically