Stop Letting a Hung Tool Call Sink Your Agent: LangGraph's TimeoutPolicy and Error Handlers

Add TimeoutPolicy and error_handler= to any LangGraph node in two extra arguments — production agents that fail gracefully instead of hanging indefinitely.

Every agent hits a slow tool eventually: a rate-limited API, a database query that stalls, an LLM call that never comes back. Without explicit fault tolerance, your LangGraph agent waits until the cloud provider drops the connection. Here's how to fix that with three primitives that attach directly to add_node().

RetryPolicy — handle transient errors automatically

from langgraph.types import RetryPolicy

retry = RetryPolicy(
    initial_interval=0.5,
    backoff_factor=2.0,
    max_attempts=3,
    retry_on=(ConnectionError, TimeoutError)
)

Exponential backoff with jitter. Only retries on the exception types you specify — other exceptions propagate immediately.

TimeoutPolicy — cap wall-clock and idle time per attempt

from langgraph.types import TimeoutPolicy

timeout = TimeoutPolicy(
    run_timeout=30.0,   # hard wall-clock cap per attempt
    idle_timeout=5.0    # fires if no progress signal for 5s
)

When a timeout fires, the attempt is cancelled and a NodeTimeoutError is raised — which counts as a retryable error for the retry policy above.

error_handler — run a recovery function after retries exhaust

from langgraph.types import NodeError, Command

def on_call_llm_failed(state: State, error: NodeError):
    log.error("LLM call failed on node %s: %s", error.node, error.error)
    return Command(update={"status": "llm_unavailable"}, goto="handle_failure")

The handler receives the failing node's name (error.node) and the exception (error.error). Returning a Command updates graph state and routes to a recovery subgraph — the Saga/compensation pattern without a try/except anywhere in your node code.

Wire it all together

builder = StateGraph(State)
builder.add_node(
    "call_llm",
    call_llm_node,
    retry=retry,
    timeout=timeout,
    error_handler=on_call_llm_failed
)

That's the full stack: retry on transient failures, cap wall-clock time, route to recovery when retries exhaust. The error handler only fires after all retry attempts have run — normal successes and retried-then-succeeded calls never touch it.

Sources: Fault Tolerance in LangGraph — LangChain Blog · LangGraph API Reference