Skip to main content
When a node fails—from a slow external API, a transient network error, or an unhandled exception—LangGraph gives you three composable mechanisms to respond:
  • Retries: automatically re-run failed attempts based on exception type and backoff settings
  • Timeouts: cap how long a single attempt may run
  • Error handling: run a recovery function after all retries are exhausted
Use setNodeDefaults to configure these mechanisms once for all nodes instead of repeating them on every addNode call. These compose in a fixed order: when a node attempt raises any exception (including NodeTimeoutError from a timeout), the retry policy decides whether to retry. Only after retries are exhausted does the error handler run. For stopping a run cleanly at a superstep boundary and resuming later, see Graceful shutdown.
Per-node timeouts and node-level error handlers require @langchain/langgraph>=1.4.0.

Retries

A retry policy automatically re-runs a failed node attempt based on exception type and backoff settings. Pass retryPolicy to addNode:

Default behavior

Retries are opt-in. A node retries only when it has a retryPolicy configured, either directly or through graph defaults with setNodeDefaults. An empty policy ({}) is enough. Without a policy, the first failure ends the attempt and LangGraph does not call retryOn. If the policy omits retryOn, LangGraph uses a built-in handler that retries thrown errors except:
  • Abort and cancellation errors: error.name === "AbortError", or error.message starts with "Cancel" or "AbortError"
  • GraphValueError, matched by error.name
  • Aborted connections: error.code === "ECONNABORTED"
  • HTTP client errors with status 400, 401, 402, 403, 404, 405, 406, 407, or 409, read from error.response?.status or error.status for clients such as fetch, Axios, and similar clients
  • OpenAI-style quota errors: error.error?.code === "insufficient_quota"
Other HTTP statuses, including 408 and 5xx responses, are retryable unless you override retryOn. NodeTimeoutError is not on this blocklist, so it is retryable when a retry policy is configured. Some failures bypass retryOn. Graph control-flow errors, such as GraphInterrupt and Command routing, bubble up without retrying. An aborted run signal also stops the retry loop, even if retryOn would return true.

Parameters

Custom retry logic

Pass a callable to retryOn. Unlike Python, there is no exported defaultRetryOn helper—implement your own predicate:

Inspect retry state

Use execution info inside a node to inspect the current attempt number. This is useful for switching to a fallback when the primary call keeps failing:
executionInfo exposes the following fields: executionInfo is available even without a retry policy—nodeAttempt defaults to 1.

Retry boundaries and idempotency

A retry re-runs the entire node function from the start. That gives at-least-once semantics for node execution: when a policy matches, LangGraph invokes the node again. It does not make external side effects happen exactly once.
Checkpoints are written at super-step boundaries, not mid-function. Graph writes from a failed attempt are discarded. Side effects during the node (payments, emails, external writes) are outside that boundary. Application code must make those effects idempotent. The same re-execution model applies after an interrupt or a crash resume. See Re-execution and idempotency. To checkpoint work inside a node so resume can skip completed units, wrap each unit in a task.

Protect side effects with an idempotency key

Send a stable idempotency key with the side effect so the provider can deduplicate retries. The key must already be durable before the side effect runs. Do not generate it inside the same node and rely on the return value:
The node never returned, so K1 was never checkpointed. A retry starts from the last committed state and generates a different key. Derive the key from state that is already durable, or persist it in a separate step that completes before the side effect:
When no durable business identity exists, persist a generated key in its own node before the side effect. Across a process crash, that only works if the intervening checkpoint is durable. Use sync durability for that pattern.
Two requirements:
  1. The key is reproducible from durable state. A retry or a resume in a fresh process reconstructs the same key.
  2. The external service honors the key. Check the provider’s documentation before relying on it.

Treat a missing acknowledgement as unknown

If the provider commits and the acknowledgement is lost, the graph has no local record even though the side effect may have happened. A later attempt with the same key avoids blind duplication when the provider deduplicates, but the outcome is still unknown. Treat missing local state as unknown, not as proof the effect did not happen. Query the provider for the operation’s status before compensating or continuing. For side effects that cannot be made idempotent at the API level, move them out of retryable nodes. For example, run them from an error handler after retries are exhausted, or from a separate worker that deduplicates by task ID.

Timeouts

Requires @langchain/langgraph>=1.4.0.
The timeout parameter on addNode caps how long a single node attempt may run. Pass a number (milliseconds) or a TimeoutPolicy for separate run and idle limits:

Run timeout

runTimeout is a hard wall-clock cap on a single attempt. It is never refreshed, regardless of node activity:
When the limit is exceeded, LangGraph raises NodeTimeoutError, clears any writes from the failed attempt, and lets the retry policy decide whether to retry.

Idle timeout

idleTimeout is a progress-resetting cap. It fires only when the node stops making observable progress for the specified duration—unlike runTimeout, the clock resets whenever the node produces a progress signal:
You can set runTimeout and idleTimeout together. Whichever fires first cancels the attempt.

Progress signals

Under the default refreshOn: "auto", the idle clock resets on any of the following:
  • State writes through the graph write path
  • Custom stream output via runtime.writer
  • Child-task scheduling
  • Any LangChain callback event from the node or its descendants (LLM tokens, tool calls, chain start/end, etc.)

Heartbeat mode

Set refreshOn: "heartbeat" to narrow the refresh source to explicit runtime.heartbeat() calls only. This is useful when you want a strict idle definition that isn’t reset by chatty subordinates:

Manual heartbeats

For long-running work that doesn’t naturally emit progress signals, call runtime.heartbeat() to manually reset the idle clock:
runtime.heartbeat() is a no-op outside an idle-timed attempt, so you can call it unconditionally.

NodeTimeoutError

When a timeout fires, LangGraph raises NodeTimeoutError with structured context about which limit was hit: Use isNodeTimeoutError(error) to narrow caught errors in TypeScript. NodeTimeoutError is retryable by default. Combining timeout with a retry policy works out of the box—the timeout clock resets on each new attempt, and writes from a timed-out attempt are cleared before the next retry:

Dynamic timeouts with Send

When using Send to dispatch nodes dynamically (for example, in map-reduce patterns), you can pass a timeout directly on the Send to override the target node’s static timeout for that specific push:
If the timeout is omitted on the Send, the target node’s timeout (set at addNode time) applies. This lets you set a default timeout on the node and tighten it for individual calls.

Error handling

Requires @langchain/langgraph>=1.4.0.
An error handler runs after a node fails and all retries are exhausted. It receives the current state and can update it or route to a different node using Command. This is useful for compensation flows (Saga patterns) where you want to recover gracefully rather than abort the entire graph. Pass errorHandler to addNode on StateGraph only (not the base Graph class):
The handler fires only after the retry policy is exhausted, or immediately if no retry policy is configured. The retry policy and the error handler stay decoupled: configure when to retry and when to compensate independently.

NodeError

Error handlers receive failure context through a typed error: NodeError parameter:
NodeError is a class with two fields: The error: NodeError parameter is opt-in. Handlers that don’t need failure context can omit the second argument and accept only state.

Route with Command

Error handlers can return a Command to update state and route to a specific node, enabling Saga / compensation patterns:
chargePayment retries on ConnectionError up to 3 times. If retries are exhausted (or the error isn’t a ConnectionError), the handler compensates by updating state and routing to finalize instead of aborting the graph.

Resume-safe failures

Failure provenance is checkpointed. If the graph is interrupted or the process crashes after a node fails but before the handler completes, the handler sees the same NodeError context when the graph resumes from its checkpoint.

Behavior with interrupt()

interrupt() raised inside a node is not routed to the error handler. Interrupts use the GraphBubbleUp mechanism to pause graph execution for human-in-the-loop workflows, bypassing both retry policies and error handlers. The graph pauses as usual.

Subgraph failures

If a node wraps a subgraph and the subgraph raises an unhandled exception, that exception surfaces to the parent node. If the parent node has an error handler, the handler fires with the subgraph’s exception in error.error.

Recovery strategies

Retries and error handlers cover automatic re-attempts and compensation after exhaustion. Two other common patterns live in your node logic:

LLM-recoverable errors

When a tool call or parse fails in a way the model can correct, catch that error in the node, write it into state, and route back to the agent so the LLM can adjust:
This is application-level control flow, not an error_handler. The node handles a known failure mode and keeps the run alive.

Unexpected errors

Do not catch failures you cannot handle. Without a matching retry policy or error handler, the exception bubbles up and fails the run so you can fix the bug:

Graph defaults

Requires @langchain/langgraph>=1.4.0.
Instead of repeating the same retryPolicy, errorHandler, timeout, or cachePolicy on every addNode call, use setNodeDefaults to configure graph-wide defaults in one place:
Both stepA and stepB now share the same retry policy, error handler, timeout, and cache policy without any duplication.

Precedence

Per-node values passed directly to addNode() always override defaults set by setNodeDefaults(). Defaults are resolved at compile() time, so you can call setNodeDefaults() before or after addNode() in any order:

Default error handler

The errorHandler default is particularly valuable when every graph run maps to an external process (for example a background job row) and any unhandled node failure should mark that process as failed, without repeating errorHandler on every addNode. Per-node handlers still take precedence when a step needs its own compensation logic:
If fetchData fails after retries, markProcessFailed runs. If chargePayment fails after retries, refundPayment runs instead because the per-node handler overrides the default.

Applicability matrix

Not all defaults apply to all node types. Error-handler nodes (those registered via addNode(..., { errorHandler })) are excluded from certain defaults to prevent unsafe behavior:

Scope

Defaults set on a parent graph are not inherited by subgraphs. Each graph maintains its own defaults.

Graceful shutdown

Cooperative shutdown lets you stop an in-flight graph run after the current superstep completes and save a resumable checkpoint. This is useful for handling SIGTERM signals or any external supervisor that needs to reclaim resources without losing work.
Requires @langchain/langgraph>=1.4.0.
Create a RunControl and pass it as control to invoke or stream. Call requestDrain() from any context to signal that the run should stop:

Semantics

Drain is cooperative and operates between supersteps, never preempting work that is already running:

Resume after drain

Resume a drained run with invoke(null, config) using the same thread_id:

Read drain state inside a node

Access drain state through the runtime parameter to adjust node behavior before the superstep boundary is reached:

SIGTERM hook pattern

The recommended pattern for handling process shutdown:
requestDrain() does not cancel in-flight async work. For a hard upper bound, pair drain with a graceful timeout and an AbortSignal.

Limitations

  • setNodeDefaults is not inherited by subgraphs: each graph manages its own defaults independently.
  • Error handlers are StateGraph-only: pass errorHandler to StateGraph.addNode, not the base Graph class. Error handlers are not available on task / entrypoint.
  • One handler per node: each node can have at most one errorHandler.
  • Handler failures bubble up: if the error handler itself throws, that exception propagates as if the node had no handler.