Error Types and Classification

Error Types and Classification

Comprehensive catalog of error types for LangGraph applications, based on the official 4-category error handling system.

Error Classification System

LangGraph provides a structured approach to error handling based on who can fix the error:

Transient Errors

Errors that usually resolve on retry. Use RetryPolicy to handle automatically.

Network Library Errors

LLM Provider Errors

HTTP Status Codes (Retryable)

Note: For exceptions from popular HTTP libraries (requests, httpx), default RetryPolicy behavior only retries 5xx status codes. 4xx errors, including 429, are not retried unless you customize retry_on.

LLM-Recoverable Errors

Errors the LLM can potentially fix if it sees the error message in state.

Parsing & Validation Errors

Tool Execution Errors

Structured Output Errors

User-Fixable Errors

Errors requiring human intervention or input.

Common Scenarios

Implementation Pattern

from langgraph.types import interrupt, Command

def requires_customer_id(state):
    if not state.get('customer_id'):
        user_input = interrupt({
            "message": "Customer ID needed",
            "request": "Please provide the customer account ID"
        })
        return Command(
            update={"customer_id": user_input['customer_id']},
            goto="requires_customer_id"  # Resume here
        )
    # Continue processing

Interrupt Response

When interrupt() is called, the graph returns:

{
  "__interrupt__": [{
    "value": {"message": "Customer ID needed", ...},
    "resumable": true,
    "ns": ["node_name:..."],
    "when": "during"
  }]
}

Resume with: Command(resume=user_input) or in SDK: client.runs.wait(thread_id, assistant_id, command={"resume": data})

Unexpected Errors (Fatal)

Errors that should bubble up for developer attention.

Python Built-in Exceptions (Not Retried by Default)

JavaScript Built-in Exceptions (Not Retried by Default)

Authentication & Authorization Errors

LangGraph-Specific Errors

Superstep Transaction Behavior

LangGraph executes nodes within supersteps - transactional units that affect error handling:

Key Behaviors

Example

# Superstep with 3 parallel nodes
workflow.add_edge(START, ["node_a", "node_b", "node_c"])

# Scenario:
# - node_a: succeeds
# - node_b: fails (retryable error)
# - node_c: succeeds

# Without RetryPolicy:
# → Entire superstep fails
# → No state updates applied
# → Graph execution stops

# With RetryPolicy on node_b:
# → node_b retries (node_a, node_c don't re-run)
# → If retry succeeds, superstep completes
# → All state updates applied together

# With Checkpointer + RetryPolicy:
# → Successful nodes (a, c) checkpointed
# → On resume, only node_b re-executes
# → Avoids repeating successful work

Resume After Failure

from langgraph.checkpoint.memory import MemorySaver

checkpointer = MemorySaver()
graph = workflow.compile(checkpointer=checkpointer)

config = {"configurable": {"thread_id": "abc123"}}

# First call: node_b fails
try:
    graph.invoke(input_data, config)
except Exception:
    pass  # Checkpoint saved

# Fix the issue (e.g., API comes back online)
# Resume from checkpoint - only failed nodes retry
result = graph.invoke(None, config)  # Resumes from checkpoint

RetryPolicy Configuration

Default Behavior

from langgraph.types import RetryPolicy

# Common explicit configuration
RetryPolicy(
    max_attempts=3,              # Total: 1 initial + 2 retries
    initial_interval=1.0,        # 1s before first retry
    backoff_factor=2.0,          # Exponential backoff
    retry_on=default_retry_on    # See "Not Retried by Default" above
)

Custom Configuration

# Retry only specific errors
workflow.add_node(
    "api_call",
    api_node,
    retry_policy=RetryPolicy(
        max_attempts=5,
        retry_on=lambda e: isinstance(e, (TimeoutError, RateLimitError))
    )
)

# Aggressive retry for critical operations
workflow.add_node(
    "database_query",
    db_node,
    retry_policy=RetryPolicy(
        max_attempts=10,
        initial_interval=0.1,
        backoff_factor=1.5,
        retry_on=sqlite3.OperationalError
    )
)

Best Practices Summary

Error Handling Checklist

• Apply RetryPolicy to nodes calling external APIs
• Configure handle_tool_errors=True on ToolNode for LLM recovery
• Use interrupt() for operations requiring human input
• Let programming errors bubble up (don't catch ValueError, TypeError)
• Use checkpointer for production to preserve progress
• Monitor logs for unexpected errors
• Test retry behavior with network failures
• Document expected error scenarios in code comments