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
npx skills add soba-labs/langchain-agent-skills --skill langgraph-error-handling -a claude-codeWhat 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
RetryPolicyto 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
ToolNodeerrors for model recovery - debug transactional failures in parallel supersteps
Example prompts for the agent
- Add
RetryPolicytocall_apifor transient failures. - Build a
Commandrecovery 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-code2Manually: put the files in place
~/.claude/skills/langgraph-error-handling/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/langgraph-error-handling/
1Skills CLI (Vercel)
npx skills add soba-labs/langchain-agent-skills --skill langgraph-error-handling -a codex2Manually: put the files in place
.agents/skills/langgraph-error-handling/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add soba-labs/langchain-agent-skills --skill langgraph-error-handling -a cursor2Manually: put the files in place
.cursor/skills/langgraph-error-handling/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install soba-labs/langchain-agent-skills skills/langgraph-error-handling2Manually: put the files in place
.github/skills/langgraph-error-handling/SKILL.md1Skills CLI (Vercel)
npx skills add soba-labs/langchain-agent-skills --skill langgraph-error-handling -a gemini-cli2Platform CLI
gemini skills install https://github.com/soba-labs/langchain-agent-skills --path skills/langgraph-error-handlingManually: put the files in place
.devin/skills/langgraph-error-handling/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add soba-labs/langchain-agent-skills --skill langgraph-error-handling -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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