Principle:Langchain ai Langgraph Error Handling
| Attribute | Value |
|---|---|
| Type | Principle |
| Knowledge Sources | LangGraph |
| Domains | Core, Error_Handling |
| Last Updated | 2026-02-11 15:00 GMT |
Overview
Error handling in LangGraph provides a structured exception hierarchy that distinguishes between different failure modes during graph compilation and execution, associating each error with machine-readable codes and troubleshooting documentation links.
Description
LangGraph defines a layered exception hierarchy designed to give both developers and the runtime precise information about what went wrong and how to fix it.
Execution limit errors -- `GraphRecursionError` is raised when a graph exceeds its configured `recursion_limit` (the maximum number of supersteps). This is the most common error developers encounter, and it typically indicates either an infinite loop in the graph topology or a limit that is too low for the task at hand.
State update errors -- `InvalidUpdateError` is raised when a channel receives an incompatible set of updates, such as concurrent writes to a non-reducer channel or a node returning a value that does not match the expected channel type.
Bubble-up exceptions -- `GraphBubbleUp` is an internal base class for exceptions that propagate upward through the graph without being treated as errors. Its subclasses include `GraphInterrupt` (used when a subgraph is interrupted and suppressed by the root graph) and `ParentCommand` (used to forward `Command` objects to a parent graph in nested graph scenarios).
Input errors -- `EmptyInputError` is raised when the graph receives an empty input payload.
Distributed execution errors -- `TaskNotFound` is raised when the task executor cannot locate a task, relevant in distributed execution modes.
Each error type is associated with an `ErrorCode` enum value that maps to a specific troubleshooting page on the LangChain documentation site. The `create_error_message` helper function generates user-facing error strings that include these documentation links, making it straightforward for developers to find resolution guidance.
Usage
Wrap `graph.invoke()` or `graph.stream()` calls in try/except blocks to catch specific error types. Catch `GraphRecursionError` to handle step limit exhaustion gracefully. Catch `InvalidUpdateError` to detect state schema mismatches during development. Use `GraphInterrupt` awareness when building systems that support human-in-the-loop workflows where graph interruption is expected behavior rather than an error.
Theoretical Basis
The error hierarchy follows the exception specialization pattern from object-oriented design, where a base exception class is progressively specialized into more specific types. This enables callers to catch errors at the appropriate level of granularity -- catching `GraphBubbleUp` to handle all non-error propagation cases, or catching `GraphInterrupt` specifically when only interrupts are relevant.
The `ErrorCode` enum and documentation URL generation implement the self-documenting error pattern, where error messages contain actionable remediation guidance rather than just a description of what went wrong. This reduces the mean time to resolution by eliminating the need to search external documentation for common failure modes.
The separation between true errors (`GraphRecursionError`, `InvalidUpdateError`) and control flow exceptions (`GraphBubbleUp`, `GraphInterrupt`) follows the principle that exceptions should represent exceptional conditions. Interrupts and parent commands are expected parts of the execution protocol, not failures, so they inherit from a distinct base class that the runtime handles differently.