`NodeTimeoutError` — which LangGraph node timeout fired

NodeTimeoutError

If you pasted that class name into a search box, one node in your LangGraph graph ran longer than a timeout someone set on it. This is not the graph-wide step limit and not a clock on the whole run. It is a per-node clock, and it comes in two kinds. Below: what the vendor’s docs say it is, read off them today, where the timeout is set, which of the two clocks fired, and the fix for each.

The definition, and the two fields that matter

LangGraph’s API reference, at reference.langchain.com/python/langgraph/errors/NodeTimeoutError, marks the class Since v1.2 and opens with:

Raised when a node invocation exceeds one of its configured timeouts.

“One of its” is the useful part: a node can carry two timeouts. The same page lists the attributes node, elapsed, kind, timeout, run_timeout and idle_timeout, with kind typed Literal['idle', 'run'], and says:

Both idle_timeout and run_timeout reflect the configured policy at the time of the failure (each is None if not configured). kind and timeout identify which one fired.

So the exception already tells you which node, which clock and how many seconds had passed. Read those before you change any number.

Where the timeout is set

LangGraph’s fault-tolerance guide, at docs.langchain.com/oss/python/langgraph/fault-tolerance, says the timeout= parameter on add_node “caps how long a single node attempt may run”, and takes a number of seconds, a timedelta or a TimeoutPolicy. If you did not write one on the node, look in three other places the same guide names:

set_node_defaults, which sets timeout once for every node in the graph.
A Send that carries its own timeout=, which overrides the target node’s timeout for that one push.
@task and @entrypoint in the functional API, which take the same timeout= parameter, with behaviour the guide calls identical to add_node.

The guide also says node timeouts apply only to async nodes, that sync nodes with a timeout are rejected at compile time, and that per-node timeouts require langgraph>=1.2.

What fires it: two clocks

kind == "run". The TimeoutPolicy reference, at reference.langchain.com/python/langgraph/types/TimeoutPolicy, calls run_timeout a “Hard wall-clock cap (in seconds) for a single node attempt. This timeout is never refreshed by progress signals or runtime.heartbeat().” The attempt was still running when that cap ran out.
kind == "idle". The same page calls idle_timeout the “Maximum time (in seconds) a single node attempt may go without observable progress.” Under the default refresh_on="auto", the fault-tolerance guide lists what counts as progress: state writes, stream output, child-task scheduling, runtime stream-writer calls, and any LangChain callback event from the node or its descendants. With refresh_on="heartbeat", only explicit runtime.heartbeat() calls count. The attempt went quiet, by that definition, for longer than the cap.

If both are set, the guide says “Whichever fires first cancels the attempt.” When one fires, LangGraph “clears any writes from the failed attempt, and lets the retry policy decide whether to retry.” The error handler, if any, runs only after retries are exhausted, or straight away if no retry policy is set.

The fix

Catch it by name and read it.

from langgraph.errors import NodeTimeoutError try: await graph.ainvoke(inputs, config) except NodeTimeoutError as e: print(e.node, e.kind, e.elapsed, e.run_timeout, e.idle_timeout) raise

Use except NodeTimeoutError, not except TimeoutError. The two vendor pages disagree here: the errors reference says the class “Does not inherit from the built-in TimeoutError (a subclass of OSError) so that the default RetryPolicy treats it as retryable”, while the graph-API guide, at docs.langchain.com/oss/python/langgraph/use-graph-api, says it “subclasses Python’s built-in TimeoutError”. Catching the class by name works under either reading.

If kind is "run": the node needed more time than you gave it. Compare elapsed with what the work really needs. Then either raise run_timeout on that node or split the work so that one attempt does less. An idle setting will not help here, because nothing refreshes this clock.

If kind is "idle": the node did work that LangGraph could not see. The guide’s answer for long work that “doesn’t naturally emit progress signals” is to call runtime.heartbeat() as it goes:

async def long_running_node(state: State, runtime: Runtime) -> State: for batch in fetch_batches(): process(batch) runtime.heartbeat() return {"result": "done"}

The guide adds that runtime.heartbeat() is a no-op outside an idle-timed attempt, so you can call it unconditionally.

Retry instead of failing, if a fresh attempt can succeed. The guide says NodeTimeoutError is retryable by default. With a retry policy on the node, such as retry_policy=RetryPolicy(max_attempts=3), “the timeout clock resets on each new attempt, and writes from a timed-out attempt are cleared before the next retry.”

One thing that looks like a timeout bug but is not: the TimeoutPolicy reference says timeouts rely on asyncio cancellation, and that if a node uses synchronous time.sleep() or other CPU-bound work that blocks the GIL, “the timeout will not be fired until after the event loop has been released.” The fault-tolerance guide’s advice for blocking I/O is asyncio.to_thread inside an async node. So if elapsed is well past the limit you set, look for blocking code in that node.

The neighbours this is not

The errors reference, at reference.langchain.com/python/langgraph/errors, lists this class next to others with their own pages here. GraphRecursionError counts steps across the graph, not seconds in one node: Recursion limit of 25 reached without hitting a stop condition. InvalidUpdateError is about conflicting writes to state, not time: InvalidUpdateError. And a run that ends on a clock set outside the graph, around the whole run, is a different wall: Why an agent run dies before its timeout.

What is behind this site

There is a written guide: the step-and-turn arithmetic as a formula you can run against a brief before you launch it, why raising a cap does not finish the job, and batch.py, one standard-library file that collapses a per-item loop into a single pass. It is $19, on a Gumroad storefront. One working way to pay today is 19 USDC on Base: you email the transaction hash and the guide is delivered by email. This page is free, ungated, and sells nothing on its own.

The short version: NodeTimeoutError is, in LangGraph’s own words, “Raised when a node invocation exceeds one of its configured timeouts.” The timeout lives on add_node, set_node_defaults, a Send, or @task/@entrypoint. Read e.kind. If it is "run", the attempt outran a hard cap: raise run_timeout or split the work. If it is "idle", the node showed no progress: call runtime.heartbeat() during long work. Add a RetryPolicy if a fresh attempt can succeed. Catch it as NodeTimeoutError, not TimeoutError.

Nearby

Recursion limit of 25 reached without hitting a stop condition — the LangGraph limit that counts steps, not seconds.
InvalidUpdateError — the one LangGraph error with its own troubleshooting guide — the same errors reference, the write-conflict entry.
Why an agent run dies before its timeout — a clock on the whole run, not on one node.
GraphInterrupt — a LangGraph pause that was never meant to reach you — the same errors reference, the entry that is not a failure.

This page counts anonymous readership with one counter, the file at /measure.js, and each of the events below is sent at most once per load. Once the page is ready it sends one view event. With it go the page path, the domain of the page you came from — only the domain, and nothing at all if you came from this site — how long the page has been open, counting only the time it was actually in front of you and not the time it sat in a background tab, whether you have scrolled, and any campaign or outreach code in the link you followed. A second event, which we call a human candidate, is sent only once the page has also received a real input event from you — a mouse movement, a touch, a scroll or a key press — and has been visible in the foreground for ten seconds in all; a program that fetches the page, or opens it and sits there, cannot produce one. A third, “engaged”, is stricter still: it is sent only after the human-candidate event, once the page has been in front of you for ninety seconds in all and you have scrolled far enough to reach a marker we put where the explaining part of this page ends; a reader who stops short of that marker never produces one. The second and third events carry the same fields as the first. If you switch away from the tab or close it, an event that has just become due may be sent as you leave. If this page has a button or a copy control that says it records a click, pressing it sends the name of that event and nothing else. Following a link to buy the guide sends one further event, also at most once per load, carrying that event’s name and a single word for which of the two checkouts you were sent to — the Gumroad listing or the payment page on this site — and nothing else: not the address you followed, not which page you were reading, not how long you had been there. Everything is sent to this site only, with no cookie attached. No cookie is read or written, nothing is put in your browser’s local or session storage, and no identifier is made from your device. Earlier versions of this page kept the campaign codes of your first visit in local storage under the name llab_attr; this page neither reads nor deletes that entry, so if it is there it stays until you clear this site’s data. An outreach code is minted per recipient, which would let us tell one reader from another; it is sent with each event and, unlike on earlier versions of this page, it is no longer removed from the address bar after it is read — if you copy the address, the code goes with it. Earlier versions also asked this domain for Vercel’s analytics script at /_vercel/insights/script.js, which on 26 September 2026 returned HTTP 404 on every host we publish; this page no longer asks for it. Your browser and the network attach things the page does not send: the identification string your browser gives, your IP address and the time of the request. The host that serves this page keeps its own request logs; those are its record and not ours.

NodeTimeoutError — which LangGraph node timeout fired