`NodeCancelledError` — a LangGraph node cancelled itself

NodeCancelledError

If you pasted that class name into a search box, code inside one node of your LangGraph graph raised asyncio.CancelledError, and LangGraph turned it into a node failure. It is not a timeout. A timeout you configured has its own exception. Below: what the vendor’s docs say it is, read off them today, how it differs from NodeTimeoutError, and the fix.

The definition

LangGraph’s API reference, at reference.langchain.com/python/langgraph/errors/NodeCancelledError, marks the class Since v1.2, lists its base as Exception and its constructor as NodeCancelledError(node: str, message: str | None = None), and opens with:

Raised when a node body raises asyncio.CancelledError itself.

The same page explains why the class exists:

asyncio.CancelledError is a BaseException and the pregel runner treats cancelled task futures as silent tear-down (e.g. when it stops sibling tasks after a peer fails). That is the correct behaviour for framework-initiated cancellation, but a user node that raises asyncio.CancelledError from its own body should surface as a node failure, the same way any other exception would.

And how it gets made: “The retry layer converts user-raised asyncio.CancelledError into this type so it flows through the normal error path and the run reports as error instead of silently succeeding.” So the error is doing you a favour. Without it, the vendor says, this run would have looked like a success.

What raises it, and what does not

Raises it: the body of a node, your code, raising asyncio.CancelledError. The attribute node holds that node’s name.
Does not raise it: cancellation that LangGraph starts itself. The reference gives the example of the runner stopping sibling tasks after a peer fails, and says that is treated as silent tear-down. Sibling tasks that LangGraph stops that way are not what this class reports.

How it differs from a timeout

A node timeout also ends an attempt by cancelling it. LangGraph’s fault-tolerance guide, at docs.langchain.com/oss/python/langgraph/fault-tolerance, says of run_timeout and idle_timeout that “Whichever fires first cancels the attempt”, and that when the limit is exceeded, “LangGraph raises NodeTimeoutError”. So a cancellation caused by a timeout= you set reaches you as NodeTimeoutError, with fields saying which clock fired and how long the node ran. A NodeCancelledError carries the node name and no clock: the cancel came from inside the node’s own code.

The fix

Catch it by name and read which node.

from langgraph.errors import NodeCancelledError try: await graph.ainvoke(inputs, config) except NodeCancelledError as e: print(e.node) raise

Then find the cancel in that node’s body. The reference says the node body raised asyncio.CancelledError itself. Look in the function registered under e.node for where that comes from. If what you wanted was a cap on how long the node may run, the guide’s tool for that is timeout= on add_node, which takes a number of seconds, a timedelta or a TimeoutPolicy and reports through NodeTimeoutError: NodeTimeoutError.

Decide whether a retry should run. The guide says the default retry_on, default_retry_on, retries on “any exception except” a listed set, and Exception, the only base the reference lists for this class, is not on that list. So, by the guide’s list, a node with retry_policy=RetryPolicy(max_attempts=3) will retry it. If a cancel from your own code means “stop”, extend the default the way the guide shows:

from langgraph.errors import NodeCancelledError from langgraph.types import RetryPolicy, default_retry_on def custom_retry_on(exc: BaseException) -> bool: if isinstance(exc, NodeCancelledError): return False return default_retry_on(exc) builder.add_node( "my_node", my_node, retry_policy=RetryPolicy(max_attempts=3, retry_on=custom_retry_on), )

Or route around it. The guide’s error_handler= on add_node runs after a node fails and all retries are exhausted. It receives a NodeError whose node is the failed node’s name and whose error is the exception raised, and it can update state or send the graph elsewhere with a Command. The guide notes that per-node timeouts and node-level error handlers require langgraph>=1.2.

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. NodeTimeoutError is the cancel that comes from a clock you set: NodeTimeoutError — which LangGraph node timeout fired. GraphRecursionError counts steps across the graph: Recursion limit of 25 reached without hitting a stop condition. InvalidUpdateError is about conflicting writes to state: InvalidUpdateError.

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: NodeCancelledError is, in LangGraph’s own words, “Raised when a node body raises asyncio.CancelledError itself.” It is not a timeout; a timeout= you set reports as NodeTimeoutError. Read e.node, find where that node’s code cancels, and either remove that cancel or use timeout= if a time cap is what you meant. Exclude it in retry_on if it should not be retried, or add an error_handler to route around it.

Nearby

NodeTimeoutError — which LangGraph node timeout fired — the same errors reference, the cancel that comes from a clock.
GraphInterrupt — a LangGraph pause that was never meant to reach you — the same errors reference, the entry that is not a failure.
InvalidUpdateError — the one LangGraph error with its own troubleshooting guide — the same errors reference, the write-conflict entry.
Recursion limit of 25 reached without hitting a stop condition — the LangGraph limit that counts steps, not seconds.

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.

NodeCancelledError — a LangGraph node cancelled itself