Implementation:Langchain ai Langgraph Error Classes

Attribute	Value
Source	`libs/langgraph/langgraph/errors.py` (127 lines)
Domain	Core, Error_Handling
Principle	Error_Handling
Library	langgraph
Import	`from langgraph.errors import GraphRecursionError, InvalidUpdateError, GraphInterrupt`

Overview

The `errors.py` module defines the error and exception hierarchy for the LangGraph core framework. It provides specialized exception classes for recursion limits, invalid state updates, graph interruptions, empty inputs, and task resolution failures, along with an `ErrorCode` enum that associates machine-readable codes with troubleshooting documentation.

Description

LangGraph uses a layered exception hierarchy to distinguish between different failure modes during graph execution:

`ErrorCode` enum -- Enumerates machine-readable error codes used to generate troubleshooting URLs:

• `GRAPH_RECURSION_LIMIT` -- the graph exceeded its maximum step count.
• `INVALID_CONCURRENT_GRAPH_UPDATE` -- concurrent updates to the same channel.
• `INVALID_GRAPH_NODE_RETURN_VALUE` -- a node returned a value incompatible with its channel.
• `MULTIPLE_SUBGRAPHS` -- multiple subgraphs detected where only one is allowed.
• `INVALID_CHAT_HISTORY` -- chat history format is invalid.

`GraphRecursionError(RecursionError)` -- Raised when the graph exhausts its `recursion_limit`. Users can increase the limit via config.

`InvalidUpdateError(Exception)` -- Raised when a channel receives an invalid set of updates, such as concurrent writes or mismatched return types.

`GraphBubbleUp(Exception)` -- Internal base class for exceptions that bubble up through the graph without being treated as errors (interrupts and parent commands).

`GraphInterrupt(GraphBubbleUp)` -- Raised when a subgraph is interrupted. This is suppressed by the root graph and never surfaces directly to the user. Stores a sequence of `Interrupt` objects.

`NodeInterrupt(GraphInterrupt)` -- Deprecated. Previously raised by a node to interrupt execution. Users should migrate to `langgraph.types.interrupt` instead. Emits a `LangGraphDeprecatedSinceV10` warning on instantiation.

`ParentCommand(GraphBubbleUp)` -- Wraps a `Command` object that should be forwarded to a parent graph.

`EmptyInputError(Exception)` -- Raised when the graph receives an empty input.

`TaskNotFound(Exception)` -- Raised when the executor cannot locate a task, relevant in distributed execution mode.

The helper function `create_error_message` produces user-facing error strings that include a link to the relevant troubleshooting page on the LangChain documentation site.

Usage

from langgraph.errors import GraphRecursionError, InvalidUpdateError, GraphInterrupt

# Catch recursion limit errors
try:
    result = graph.invoke({"messages": ["Hello"]}, {"recursion_limit": 5})
except GraphRecursionError:
    print("Graph exceeded recursion limit")

Code Reference

ErrorCode Enum

Member	Value	Description
`GRAPH_RECURSION_LIMIT`	`"GRAPH_RECURSION_LIMIT"`	Graph exceeded maximum step count.
`INVALID_CONCURRENT_GRAPH_UPDATE`	`"INVALID_CONCURRENT_GRAPH_UPDATE"`	Concurrent updates to the same channel.
`INVALID_GRAPH_NODE_RETURN_VALUE`	`"INVALID_GRAPH_NODE_RETURN_VALUE"`	Node returned incompatible value.
`MULTIPLE_SUBGRAPHS`	`"MULTIPLE_SUBGRAPHS"`	Multiple subgraphs where only one is allowed.
`INVALID_CHAT_HISTORY`	`"INVALID_CHAT_HISTORY"`	Chat history format is invalid.

Exception Classes

Class	Base Class	Description
`GraphRecursionError`	`RecursionError`	Graph exhausted its maximum number of steps.
`InvalidUpdateError`	`Exception`	Invalid set of updates applied to a channel.
`GraphBubbleUp`	`Exception`	Internal base for non-error bubble-up exceptions.
`GraphInterrupt`	`GraphBubbleUp`	Subgraph interrupted; suppressed by root graph.
`NodeInterrupt`	`GraphInterrupt`	Deprecated. Node-initiated interrupt. Use `langgraph.types.interrupt` instead.
`ParentCommand`	`GraphBubbleUp`	Wraps a `Command` to forward to the parent graph.
`EmptyInputError`	`Exception`	Graph received an empty input.
`TaskNotFound`	`Exception`	Executor unable to find a task (distributed mode).

Helper Function

Function	Signature	Description
`create_error_message`	`(*, message: str, error_code: ErrorCode) -> str`	Builds an error message string with a link to the troubleshooting documentation.

I/O Contract

Aspect	Detail
Input	Exceptions are raised by the LangGraph runtime during graph compilation and execution.
Output	Standard Python exception objects with descriptive messages and troubleshooting URLs.
Side Effects	`NodeInterrupt.__init__` emits a `LangGraphDeprecatedSinceV10` deprecation warning.

Usage Examples

Handling Recursion Limits

from langgraph.errors import GraphRecursionError

try:
    result = graph.invoke(
        {"messages": [("user", "Hello, world!")]},
        {"recursion_limit": 1000},
    )
except GraphRecursionError as e:
    print(f"Recursion limit reached: {e}")

Handling Invalid Updates

from langgraph.errors import InvalidUpdateError

try:
    graph.update_state(config, values={"bad_key": "value"})
except InvalidUpdateError as e:
    print(f"Invalid state update: {e}")

Using ErrorCode for Diagnostics

from langgraph.errors import ErrorCode, create_error_message

msg = create_error_message(
    message="Step limit exceeded",
    error_code=ErrorCode.GRAPH_RECURSION_LIMIT,
)
# "Step limit exceeded\nFor troubleshooting, visit: https://docs.langchain.com/..."

Related Pages

• Langchain_ai_Langgraph_Public_Constants -- Constants like `START` and `END` used in graph topology.
• Langchain_ai_Langgraph_Warnings -- Deprecation warning classes used by `NodeInterrupt`.
• Langchain_ai_Langgraph_PregelProtocol -- The protocol whose execution raises these errors.
• Langchain_ai_Langgraph_SDK_Errors -- SDK-level error hierarchy for API communication errors.