`GraphInterrupt` — a LangGraph pause that was never meant to reach you

GraphInterrupt

If you pasted that class name into a search box, it most likely reached you as an error: in a traceback, in a log line, or as a red mark in a tracing or error dashboard. LangGraph’s own reference says it should never get that far. It is how a graph pauses to wait for input, not a sign that the run broke. Below: what the vendor’s docs say it is, read off them today, where it gets out, and how to put it back.

The definition, and the half that matters

LangGraph’s API reference, at reference.langchain.com/python/langgraph/errors/GraphInterrupt, gives the class two sentences:

Raised when a subgraph is interrupted, suppressed by the root graph. Never raised directly, or surfaced to the user.

The second sentence is the useful one. The vendor says this exception is not supposed to be surfaced to you. So seeing it does not mean the graph failed. It means a pause got out of the place where the runtime normally catches it. The same reference page lists the class as based on GraphBubbleUp, and its constructor takes one argument, interrupts, typed Sequence[Interrupt]. In other words, the exception is a carrier for the questions your graph wanted to ask. It is not a fault report.

How a pause becomes an exception

The mechanism is in LangGraph’s interrupts guide, at docs.langchain.com/oss/python/langgraph/interrupts:

When you call interrupt within a node, LangGraph suspends execution by raising an exception that signals the runtime to pause. This exception propagates up through the call stack and is caught by the runtime, which notifies the graph to save the current state and wait for external input.

That is the whole story in one paragraph. An interrupt() call does not return until you resume. Instead it raises, and the exception travels up through every frame between your node and the runtime. Anything in that path that catches exceptions, or just watches them go by, sees something that looks like a failure. Most of the ways people end up reading GraphInterrupt come down to code sitting in that path.

Where it gets out

A broad try/except around the call. The same guide states the rule plainly: “If you wrap the interrupt call in a try/except block, you will catch this exception and the interrupt will not be passed back to the graph.” The sign is a printed or logged exception where you expected a pause. The graph then carries on as if nobody was ever asked.
Something that records every exception as it passes. A tracer, an error hook, a logger set to record raised exceptions, an error-rate metric. Propagating up the call stack is the documented way a pause works, so a hook that counts every exception it sees will count every pause as an error. Your dashboard is not wrong about what it saw. It just has no category for a pause.
A retry wrapper. A wrapper that catches the exception and runs the node again treats a question as a failure. The guide also notes that on resume “the runtime restarts the entire node from the beginning” and “any code that ran before the interrupt will execute again”. So every extra run of that node repeats whatever side effects come before the interrupt() call.

The fix

Keep the call out of a bare except. The guide’s two approved patterns are to call interrupt() first and handle error-prone code separately, or to catch only specific exception types. If a broad handler has to stay, let the pause through before it does anything else:

from langgraph.errors import GraphInterrupt try: answer = interrupt("Approve this action?") do_the_risky_thing() except GraphInterrupt: raise # a pause, not a failure: hand it back to the runtime except Exception as e: log_failure(e)

Teach your error hook the difference. In whatever records failures, classify by class before you count. Record GraphInterrupt as waiting for input and leave it out of your error rate. The reference names its base class, GraphBubbleUp, but filtering on GraphInterrupt itself is the narrower choice: it lets through only what you have read about here.

Read the pause where the vendor puts it. According to the interrupts guide, the default invoke() API surfaces interrupts under result["__interrupt__"]. With event streaming (graph.stream_events(..., version="v3")), the payloads appear on stream.interrupts and stream.interrupted is True when the run pauses for input. Check one of those, not the exception.

Resume on the same thread. The guide lists what a pause needs: a checkpointer and a thread ID in your config. You resume with Command(resume=...), whose value “becomes the return value of the interrupt call”. Reuse the same thread_id. In the guide’s words, “Reusing it resumes the same checkpoint; using a new value starts a brand-new thread with an empty state.”

One more thing to do once, not every time: because the node restarts from the beginning on resume, make everything above the interrupt() line safe to run twice. A pause that leaks is noisy. A pause that charges a card twice is a bug report.

The neighbours this is not

The same errors reference, at reference.langchain.com/python/langgraph/errors, lists NodeInterrupt as deprecated, with the line “Raised by a node to interrupt execution.” If old code raises that one on purpose, it is the older route to the same pause. Two entries above GraphInterrupt sits GraphRecursionError. That one is a real stop: the graph ran out of steps. It has its own page here: Recursion limit of 25 reached without hitting a stop condition.

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: GraphInterrupt is, in LangGraph’s own words, “Raised when a subgraph is interrupted, suppressed by the root graph. Never raised directly, or surfaced to the user.” interrupt() pauses a graph by raising an exception that the runtime is meant to catch. If you are reading it, something in between caught it first or recorded it on the way past: a bare except, an error hook, or a retry wrapper. Re-raise it, count it as waiting rather than failed, read the pause from __interrupt__ or stream.interrupted, and resume with Command(resume=...) on the same thread_id.

Nearby

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 stop that really is a stop.
recursion_limit, max_iter, max_turns: one wall under four names — what each framework calls the step ceiling and what each does on contact.
Why an agent run dies before its timeout — the same kind of wall read off the clock, with the arithmetic that predicts it.

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.

GraphInterrupt — a LangGraph pause that was never meant to reach you