Error Recovery

Handle Claude Code errors gracefully with systematic recovery strategies and prevention techniques.

Quick Reference

Error Category	Common Causes	Quick Fix
API Errors	Rate limits, overload, auth	Wait, retry, check credentials
Tool Errors	Permissions, missing files	Check permissions, validate paths
Context Errors	Token overflow, corruption	/compact or /clear
MCP Errors	Server disconnect, timeout	Restart server, check logs
Hook Errors	JSON syntax, script failure	Validate JSON, test script

Error Message Anatomy

Claude Code error messages follow a consistent pattern:

[Error Category] [Specific Error]: [Description]
  at [Location/Context]
  Cause: [Root cause if known]
  Suggestion: [Recommended action]

Reading Error Messages

Part	What It Tells You	Action
Category	Type of error (API, Tool, etc.)	Determines recovery approach
Specific Error	Exact error code/name	Look up in error reference
Description	Human-readable explanation	Understand what went wrong
Location	Where error occurred	Identify failing component
Cause	Why it happened	Fix root cause
Suggestion	Recommended fix	Try suggested action first

Common Error Patterns

API Errors

Error	Meaning	Recovery
rate_limit_error	Too many requests	Wait 60s, reduce frequency
overloaded_error	API at capacity	Wait 30-60s, retry
context_length_exceeded	Too many tokens	/compact or split request
authentication_error	Invalid/expired token	claude auth login
invalid_request_error	Malformed request	Check input format
api_error	Server-side issue	Retry with backoff

Tool Errors

Error	Meaning	Recovery
permission_denied	Tool not allowed	/permissions, allow tool
file_not_found	Path doesn't exist	Verify path, check working dir
directory_not_found	Dir doesn't exist	Create directory first
read_error	Can't read file	Check permissions, encoding
write_error	Can't write file	Check permissions, disk space
command_failed	Bash command error	Check exit code, stderr
timeout	Operation too slow	Increase timeout, simplify

Context Errors

Error	Meaning	Recovery
context_overflow	Token limit reached	/compact or /clear
memory_limit	Too much in memory	Clear memory banks
session_expired	Session timed out	Start new session
state_corruption	Session state invalid	/clear, restart

Recovery Workflow

Step 1: Identify Error Type

Error occurred
    |
    +-- API Error?
    |   +-- Yes --> See API recovery
    |   +-- No --> Continue
    |
    +-- Tool Error?
    |   +-- Yes --> See Tool recovery
    |   +-- No --> Continue
    |
    +-- Context Error?
    |   +-- Yes --> See Context recovery
    |   +-- No --> Continue
    |
    +-- Unknown?
        +-- Check debug output
        +-- Use /bug to report

Step 2: Apply Recovery Strategy

For API Errors:

1. Wait for rate limit window (60s typical)
2. Retry with exponential backoff
3. If persistent, check credentials

For Tool Errors:

1. Check /permissions
2. Validate inputs (paths, arguments)
3. Check file/directory exists

For Context Errors:

1. Run /compact to reduce context
2. If severe, use /clear
3. Start fresh if corrupted

Step 3: Verify Recovery

# Check system health
claude doctor

# Verify specific component
/permissions  # Tool permissions
/mcp          # MCP servers
/hooks        # Hook status

Quick Recovery Commands

Situation	Command
Context too large	/compact
Session corrupted	/clear
Need to restart	Ctrl+C, restart claude
Check health	claude doctor
Debug mode	claude --debug
Verbose logging	ANTHROPIC_LOG=debug claude

Retry Patterns

Simple Retry

For transient errors (rate limits, overload):

1. Wait initial delay (1s)
2. Retry operation
3. If fails, double delay (2s, 4s, 8s...)
4. Max 5 retries or 60s total
5. If still failing, escalate

Backoff with Jitter

For high-contention scenarios:

delay = min(cap, base * 2^attempt) + random(0, 1000ms)

• Base: 1000ms
• Cap: 60000ms
• Jitter: 0-1000ms random

Circuit Breaker

For persistent failures:

If 3 failures in 60s:
    Open circuit (stop trying)
    Wait 5 minutes
    Try once (half-open)
    If success: close circuit
    If failure: keep open

Error Prevention Checklist

Before operations:

• Validate file paths exist
• Check permissions are granted
• Verify network connectivity
• Ensure context has headroom
• Test hooks work correctly

During operations:

• Watch for warning signs
• Monitor context size
• Handle errors gracefully
• Log important state

After errors:

• Document what happened
• Fix root cause
• Add prevention measures
• Test fix works

Reference Files

File	Contents
ERROR-TYPES.md	Comprehensive error reference
RECOVERY-PATTERNS.md	Recovery strategies and patterns
PREVENTION.md	Error prevention techniques

Common Scenarios

Scenario: Rate Limited

Symptom: rate_limit_error after many requests

Solution:

1. Wait 60 seconds
2. Reduce request frequency
3. Batch operations when possible

Scenario: Context Overflow

Symptom: context_length_exceeded error

Solution:

1. Run /compact to summarize context
2. If still too large, /clear and restart
3. Use smaller file reads (with offset/limit)

Scenario: Tool Permission Denied

Symptom: Tool blocked by permissions

Solution:

1. Run /permissions
2. Allow the specific tool
3. Or add to settings.json for persistence

Scenario: MCP Server Disconnected

Symptom: MCP tools return errors

Solution:

1. Check /mcp for server status
2. Restart MCP server if needed
3. Verify .mcp.json configuration

Best Practices

1. Fail Fast: Validate early, fail before expensive operations
2. Graceful Degradation: Have fallbacks for non-critical features
3. Clear Errors: Provide actionable error messages
4. Log Everything: Enable debug mode when troubleshooting
5. Test Recovery: Verify recovery procedures work before you need them

When to Escalate

Use /bug command when:

• Error persists after recovery attempts
• Error message is unclear or missing
• Behavior contradicts documentation
• Reproducible crash occurs

Include in report:

• Claude Code version
• Error message (full text)
• Steps to reproduce
• Debug output