Skip to main content
skill CX Codex

langgraph-error-handling — Claude Code skill for LangGraph

The langgraph-error-handling Claude Code skill adds error-handling patterns to LangGraph. It applies to transient failures, model recovery, and workflows that need human approval.

MIT ★ 106 updated 2026-11-11

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add soba-labs/langchain-agent-skills --skill langgraph-error-handling -a claude-code
Open on GitHub

What langgraph-error-handling does

The skill helps build LangGraph error paths: retry a transient failure, route back through Command after a model or tool correction, or pause for human input with interrupt() and resume. It also covers ToolNode errors and explains that a failed parallel branch cancels the state update for its whole superstep.

Scripts classify exceptions and generate node-wrapper boilerplate. The bundled examples show retry and approval flows in Python and JS. Interrupt flows require a checkpointer, and resuming must reuse the same thread_id. JS nodes that route with Command need ends metadata in addNode; retries and recovery loops need explicit limits.

What it helps with

  • add RetryPolicy to nodes with transient API or database failures
  • route an LLM back to a tool after correcting its arguments
  • pause a graph for human approval and resume it afterward
  • shape ToolNode errors for model recovery
  • debug transactional failures in parallel supersteps

Example prompts for the agent

  • Add RetryPolicy to call_api for transient failures.
  • Build a Command recovery loop that lets the LLM correct tool arguments.
  • Add human approval with interrupt() and resume the graph.

How to install langgraph-error-handling

1Skills CLI (Vercel)

npx skills add soba-labs/langchain-agent-skills --skill langgraph-error-handling -a claude-code

2Manually: put the files in place

~/.claude/skills/langgraph-error-handling/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/langgraph-error-handling/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about langgraph-error-handling

How do I install langgraph-error-handling in Claude Code?

Run npx skills add soba-labs/langchain-agent-skills --skill langgraph-error-handling -a claude-code. The skill file is at ~/.claude/skills/langgraph-error-handling/SKILL.md.

What does langgraph-error-handling do?

It provides patterns for retrying transient failures, routing model recovery with Command, and pausing for human approval with interrupt(). It also covers ToolNode errors and failures in parallel supersteps.

What does langgraph-error-handling require for interrupt() flows?

Compile the graph with a checkpointer. Resume with the same thread_id.

Source text

SKILL.md · MIT
---
name: langgraph-error-handling
description: Implement LangGraph error handling with current v1 patterns. Use when users need to classify failures, add RetryPolicy for transient issues, build LLM recovery loops with Command routing, add human-in-the-loop with interrupt()/resume, handle ToolNode errors, or choose a safe strategy between retry, recovery, and escalation.
---

# LangGraph Error Handling

## Use This Skill For
- Adding `RetryPolicy` to flaky nodes (API, DB, model/tool calls)
- Designing LLM recovery loops (`Command` + error state + retry counters)
- Adding human approval/escalation with `interrupt()` and resume
- Handling prebuilt `ToolNode` failures
- Debugging transactional failure behavior in parallel supersteps

## Strategy Selection

Use this order:

1. Transient/infrastructure issue (`429`, timeout, `5xx`, temporary DB lock) -> `RetryPolicy`
2. Recoverable by model/tool args correction -> store error in state and route back with `Command`
3. Needs user approval or missing info -> `interrupt()` + resume
4. Unknown/programming bug -> let it bubble up and debug

| Error Type | Owner | Primary Mechanism |
|---|---|---|
| Transient | System | `RetryPolicy` |
| LLM-recoverable | LLM | State update + `Command(goto=...)` |
| User-fixable | Human | `interrupt()` + `Command(resume=...)` |
| Unexpected | Developer | Raise/log/debug |

For full taxonomy, load [references/error-types.md](references/error-types.md).

## Minimal Patterns

### 1) Retry Transient Failures

```python
from langgraph.types import RetryPolicy

builder.add_node(
    "call_api",
    call_api,
    retry_policy=RetryPolicy(max_attempts=3, initial_interval=1.0),
)
```

```ts
builder.addNode("callApi", callApi, {
  retryPolicy: { maxAttempts: 3, initialInterval: 1.0 },
});
```

Notes:
- Python and JS default retry behavior differs by exception type.
- Prefer targeted `retry_on`/`retryOn` for non-transient domains.

### 2) LLM Recovery Loop

Use `MessagesState` in Python for message state.

```python
from typing import Literal
from typing_extensions import NotRequired
from langgraph.graph import MessagesState
from langgraph.types import Command

class State(MessagesState):
    error: NotRequired[str]
    retry_count: NotRequired[int]

def agent(state: State) -> Command[Literal["tool", "__end__"]]:
    if state.get("retry_count", 0) >= 3:
        return Command(goto="__end__")
    if state.get("error"):
        return Command(goto="tool")
    return Command(goto="tool")
```

```ts
import { StateGraph, Command, END } from "@langchain/langgraph";

// If a node returns Command in JS, add `ends` on addNode.
builder.addNode("agent", agentNode, { ends: ["tool", END] });
```

### 3) Human-In-The-Loop Escalation

```python
from langgraph.types import interrupt, Command

def human_review(state):
    approved = interrupt({
        "question": "Proceed?",
        "payload": state["pending_action"],
    })
    return Command(goto="execute" if approved else "cancel")

# resume
graph.invoke(Command(resume=True), config={"configurable": {"thread_id": "t-1"}})
```

```ts
import { Command, interrupt } from "@langchain/langgraph";

const approved = interrupt({ question: "Proceed?" });
// later
await graph.invoke(new Command({ resume: true }), {
  configurable: { thread_id: "t-1" },
});
```

Requirements:
- Compile with a checkpointer for interrupt flows.
- Reuse the same `thread_id` on resume.

For deep HITL patterns, load [references/human-escalation.md](references/human-escalation.md).

## ToolNode Error Handling

```python
from langgraph.prebuilt import ToolNode

tool_node = ToolNode(tools, handle_tool_errors=True)
tool_node = ToolNode(tools, handle_tool_errors="Please try again.")
tool_node = ToolNode(tools, handle_tool_errors=(ValueError, TypeError))
```

Use custom handlers when you need deterministic error shaping for model recovery.
For broader tool-recovery design, load [references/llm-recovery.md](references/llm-recovery.md).

## Critical Behavior (Do Not Skip)

1. **Supersteps are transactional**: one failing parallel branch fails the whole superstep state update.
2. **RetryPolicy retries failing branches**, not successful siblings.
3. **`interrupt()` re-runs the node on resume**: side effects before interrupt must be idempotent, or moved after interrupt / separate node.
4. **JS `Command` routing requires `ends` metadata** on `addNode(...)`.
5. **Use explicit retry limits** (`max_attempts`, plus state counters for recovery loops).

## Local Assets In This Skill

### Scripts
- `scripts/classify_error.py`: classify exception category and recommended handling
- `scripts/wrap_with_retry.py`: generate boilerplate node wrappers with retry/recovery/escalation options

Run from repo root:

```bash
uv run skills/langgraph-error-handling/scripts/classify_error.py TimeoutError --verbose
uv run skills/langgraph-error-handling/scripts/wrap_with_retry.py call_llm --with-llm-recovery
```

### Examples
- `assets/examples/retry-example/`: retry + recovery loop (Python and JS)
- `assets/examples/human-loop-example/`: interrupt/resume approval flow (Python and JS)

## Load References On Demand

- `references/error-types.md`: error taxonomy and classification rules
- `references/retry-strategies.md`: retry tuning, backoff, circuit-breaker-style patterns
- `references/llm-recovery.md`: recovery-loop and ToolNode strategies
- `references/human-escalation.md`: human approval, interrupts, and escalation patterns

## Common Failure Modes

| Symptom | Root Cause | Fix |
|---|---|---|
| `interrupt()` fails at runtime | no checkpointer | compile with checkpointer |
| Resume starts new run | different `thread_id` | reuse same `thread_id` |
| JS Command route not taken | missing `ends` | add `ends` to `addNode` |
| Infinite loop | no termination counter/condition | add retry counter + terminal branch |
| Retry never triggers | exception excluded by retry filter | set explicit `retry_on`/`retryOn` |

© soba-labs · MIT · soba-labs/langchain-agent-skills

Similar skills

All skills for AI and ML →

From the same set9

langsmith-trace-analyzer The langsmith-trace-analyzer Claude Code skill downloads and analyzes LangSmith traces. It helps investigate agent runs and compare evaluation results. CX Codex +1 ★ 106repo stars langsmith-deployment This Claude Code skill manages agent server deployments in LangSmith Deployment. It comes into play when validating langgraph.json, changing revisions, or diagnosing runtime issues. CX Codex +1 ★ 106repo stars langgraph-testing-evaluation langgraph-testing-evaluation — a skill for Claude Code tests and evaluates LangGraph and LangChain agents. It supports test scaffolds, trajectory scoring, dataset runs, and version comparisons. CX Codex +1 ★ 106repo stars langgraph-state-management The langgraph-state-management Claude Code skill helps shape state schemas for LangGraph applications and diagnose update behavior. It applies to reducer design, persistence setup, and checkpoint debugging. CX Codex +1 ★ 106repo stars langgraph-project-setup The langgraph-project-setup Claude Code skill scaffolds and configures LangGraph projects. It activates for project structure, langgraph.json, provider variables, dependency setup, and configuration troubleshooting. CX Codex +1 ★ 106repo stars langgraph-agent-patterns The langgraph-agent-patterns Claude Code skill helps build agent coordination patterns for LangGraph applications. It activates when choosing a pattern or debugging how agents work together. CX Codex +1 ★ 106repo stars deepagents-setup-configuration The deepagents-setup-configuration Claude Code skill scaffolds and checks Deep Agents projects in Python or JavaScript. It helps configure subagents, persistence, and human approval. CX Codex +1 ★ 106repo stars deepagents-planning-todos The deepagents-planning-todos Claude Code skill shows how to plan Deep Agents work with write_todos. It covers task breakdown, progress tracking, and diagnosing todos that remain unfinished. CX Codex +1 ★ 106repo stars

Project sponsors

Companies that keep this analytics open