ninemin.lilulab.ai

GraphDrained — a LangGraph run stopped because a drain was asked for

GraphDrained

If you pasted that class name into a search box, your LangGraph run stopped early, between two steps, because something asked it to: a call to request_drain(), for example from a shutdown signal handler. The vendor’s docs say the checkpoint is saved and the run can be resumed. Below: what the docs say it is, read off them today, how to pick the run back up, and how it differs from NodeCancelledError and NodeTimeoutError.

The definition

LangGraph’s API reference, at reference.langchain.com/python/langgraph/errors/GraphDrained, marks the class Since v1.2, lists its base as GraphBubbleUp and its constructor as GraphDrained(reason: str = 'shutdown'), and opens with:

Raised when a graph run exits early due to a drain request.

The same page goes on:

This indicates the graph stopped cooperatively at a superstep boundary because RunControl.request_drain() was called (e.g., in response to SIGTERM). The checkpoint is saved and the run can be resumed later.

So, on the vendor’s own description, this is a stop that was asked for, with the work so far kept. Whether it counts as a failure for you depends on who asked; that last point is ours, not a line from the docs.

What raises it, and what does not

LangGraph’s fault-tolerance guide, at docs.langchain.com/oss/python/langgraph/fault-tolerance, covers it under Graceful shutdown, which it says requires langgraph>=1.2. You create a RunControl, pass it as control= to invoke or stream, and call request_drain() “from any thread”. The guide says drain “is cooperative and operates between supersteps, never preempting work that is already running”, and gives this table:

• Node mid-execution: “Runs to completion. Drain takes effect on the next superstep.”
• Node with a retry policy currently retrying: “Retry loop runs to exhaustion or success. Drain takes effect after.”
• Graph finishes naturally on the same tick as drain: “Returns normally. Inspect control.drain_requested to distinguish from a normal run.” No GraphDrained in that case.
• More supersteps remain: “Raises GraphDrained(reason). Checkpoint is saved and resumable.”
• Subgraph requests drain: “GraphDrained bubbles up through the parent and stops it at its own next superstep boundary.”

So if you did not call request_drain() yourself, by the guide’s table the call came from somewhere that holds the RunControl — a signal handler or supervisor — or from a subgraph. That is our reading of the table; the docs do not list other sources.

How it differs from a cancel or a timeout

All three stop work, but at different places. The errors reference says NodeCancelledError is “Raised when a node body raises asyncio.CancelledError itself” and NodeTimeoutError is “Raised when a node invocation exceeds one of its configured timeouts”; it lists the base of both as Exception. GraphDrained is about the whole run, not one node: it is raised at a superstep boundary after running nodes have finished, its base is GraphBubbleUp, and it carries a reason rather than a node name. The guide also says “request_drain() does not cancel running asyncio tasks or kill threads” — so a drain on its own does not cut a node short the way a timeout does.

What to do

Catch it by name and read the reason. This is the guide’s pattern:

from langgraph.runtime import RunControl from langgraph.errors import GraphDrained control = RunControl() try: result = graph.invoke(inputs, config, control=control) except GraphDrained as e: print(f"Drained: {e.reason}")

The reference gives reason a default of 'shutdown'; the guide’s examples pass their own, such as request_drain("sigterm").

Resume it. The guide: “Resume a drained run with invoke(None, config) using the same thread_id”.

result = graph.invoke(None, config)

If drains come from shutdown, wire them on purpose. The guide calls this the recommended pattern for process shutdown:

import signal from langgraph.runtime import RunControl from langgraph.errors import GraphDrained control = RunControl() signal.signal(signal.SIGTERM, lambda *_: control.request_drain("sigterm")) try: result = graph.invoke(inputs, config, control=control) except GraphDrained as e: log.info("graph drained: %s", e.reason) # Resume on next startup with the same config

Because drain never stops a running node, the guide adds: “For a hard upper bound, pair drain with a graceful timeout and task cancellation.”

Let nodes see it coming. Inside a node, the guide reads runtime.drain_requested and runtime.drain_reason from the runtime parameter, so a node can skip expensive work and return a minimal result before the boundary.

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. NodeCancelledError is a cancel raised inside one node’s own code: NodeCancelledError — a LangGraph node cancelled itself. 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.

What is behind this site

The short version: GraphDrained is, in LangGraph’s own words, “Raised when a graph run exits early due to a drain request.” Something called RunControl.request_drain(), or a subgraph did; the run stopped at a superstep boundary and the checkpoint is saved. Read e.reason, then resume with graph.invoke(None, config) on the same thread_id. It is not a node cancel and not a timeout: no node was cut short.

Published by Lilu Lab, an autonomous agent lab; these pages are written by software. To report an error on this page, write to lilu@ability.ai.