Error Recovery & Resilience

Learn to handle failures gracefully, recover from errors, and build resilient workflows with Claude Code. This guide covers everything from simple retries to complex recovery strategies, ensuring your AI-assisted development stays productive even when things go wrong.

Understanding Claude Code Errors

Common Error Categories

Claude Code errors typically fall into these categories:

1. Permission Errors - Tool execution blocked
2. Context Errors - Token limits or memory issues
3. Execution Errors - Command failures or syntax issues
4. Connection Errors - Network or MCP server issues
5. Model Errors - AI confusion or incorrect outputs

Error Indicators

Claude provides clear visual feedback when errors occur:

1. Red error messages - Direct command failures
2. Yellow warnings - Non-critical issues
3. Tool execution failures - Clear error output
4. Retry suggestions - Claude often suggests fixes

Permission-Based Recovery

The Permission Problem

By default, Claude asks permission for every potentially risky operation:

# This gets interrupted constantly:
claude "Refactor the authentication system"
# → "Can I edit auth/login.js?" [y/n]
# → "Can I run git add?" [y/n]
# → "Can I edit auth/session.js?" [y/n]

Solution 1: Skip Permissions (Recommended for Development)

YOLO Mode

# Skip all permission prompts for uninterrupted workflow
claude --dangerously-skip-permissions

This mode is safe for:

• Development environments
• Containerized workspaces
• Projects with good backups

Solution 2: Configure Allowed Tools

1. Use /permissions command to manage allowed tools
2. Add specific tools to allowlist: Edit, View, Bash(git:*)
3. Save preferences in .claude/settings.json:

{
  "allowedTools": [
    "Edit",
    "View",
    "Bash(git:*)",
    "Bash(npm:*)",
    "mcp__git__*"
  ]
}

Solution 3: Session-Specific Permissions

# Allow specific tools for this session only
claude --allowedTools "Edit,View,Bash(git:*)"

Execution Error Recovery

Command Failures

When commands fail, Claude typically:

1. Shows the error - Full stderr output
2. Analyzes the cause - Identifies what went wrong
3. Suggests fixes - Proposes solutions
4. Retries automatically - If you approve

Tip

Claude learns from errors within a session. If npm install fails due to permissions, it might suggest using a different approach or fixing permissions first.

Manual Recovery Techniques

Undo Changes

# Undo the last change
/undo

# Or ask Claude to revert
"Please undo the last file edit"

# Git-based recovery
"git checkout -- filename.js"

Edit Recovery

# If an edit goes wrong
"The last change broke the syntax, please fix it"

# Claude will re-read the file and correct errors

Session Recovery

# Fork from a previous point
# Press Esc twice, then select a previous message

# Or start fresh
/clear

Context and Memory Errors

Token Limit Recovery

When hitting context limits:

1. Clear unnecessary context: /clear
2. Start a new session with focused context
3. Export important state to CLAUDE.md
4. Use modular memory files

Context Management Pattern

# In CLAUDE.md
## Current Task State
- Completed: Authentication refactor
- In Progress: Session management
- Next: Testing implementation

## Key Decisions
- Using JWT for sessions
- Redis for session storage
- 24-hour expiration

Memory Overflow Prevention

# Before context gets too large
claude "Save our current progress to CLAUDE.md"

# Then clear and continue
/clear
claude "Continue from CLAUDE.md progress"

Connection and MCP Errors

MCP Server Recovery

Connection Issues

# Check MCP server status
claude mcp list

# Restart specific server
# (Restart the application providing the server)

# Debug MCP issues
claude --mcp-debug

Timeout Issues

# Increase timeout for slow operations
export MCP_TIMEOUT=30000  # 30 seconds

# Or configure in settings
{
  "mcpTimeout": 30000
}

Configuration Errors

# Validate MCP configuration
cat .mcp.json | jq .

# Test individual server
claude "Test the GitHub MCP connection"

Model Confusion Recovery

When Claude Gets Confused

Signs of model confusion:

• Repeating the same errors
• Misunderstanding requirements
• Going in circles
• Suggesting incorrect solutions

Recovery Strategies

1. Clear and restart with better context
2. Break down the problem into smaller parts
3. Provide explicit examples of desired outcome
4. Switch models if available
5. Use structured prompts with clear steps

Confusion Recovery Template

Let's restart. Here's what we need:

1. Current state: [describe what exists]
2. Desired outcome: [describe what you want]
3. Constraints: [any limitations]
4. Example: [provide a concrete example]

Please approach this step-by-step.

Advanced Recovery Patterns

Checkpoint-Based Recovery

Create recovery checkpoints during complex operations:

# Before risky changes
git add -A && git commit -m "Checkpoint: before auth refactor"

# Or use Claude
claude "Create a git checkpoint before we proceed"

Structured Error Handling

Implement error-aware workflows:

# Tell Claude to be defensive
claude "Implement the API client with comprehensive error handling"

# Claude will add try-catch blocks, validation, and fallbacks

Recovery Scripts

Create recovery commands in .claude/commands/:

.claude/commands/recover.md

When recovering from errors:
1. Run git status to check changes
2. Run tests to verify functionality
3. Check logs for recent errors
4. Restore from last known good state if needed

Execute: $ARGUMENTS

Troubleshooting Guide

Common Issues and Solutions

Installation Issues

NPM Permission Errors:

# Fix npm prefix
npm config set prefix ~/.npm-global
export PATH=$PATH:~/.npm-global/bin

# Or migrate to local install
claude migrate-installer

Missing Commands:

# Verify installation
which claude
claude doctor

# Reinstall if needed
npm install -g @anthropic-ai/claude-code

Authentication Issues

Login Problems:

# Clear auth and restart
rm -rf ~/.config/claude-code/auth.json
claude

# Or use /logout command
/logout

API Key Issues:

# Check environment
echo $ANTHROPIC_API_KEY

# Set if missing
export ANTHROPIC_API_KEY="your-key"

Performance Issues

High CPU/Memory:

# Check Claude processes
ps aux | grep claude

# Restart if needed
pkill -f claude
claude

Slow Responses:

• Clear context with /clear
• Reduce file includes
• Use focused prompts
• Check network connectivity

Building Resilient Workflows

Error-Tolerant Patterns

Resilient Development Flow

1. Always work in branches - Easy rollback
2. Commit frequently - More recovery points
3. Test incrementally - Catch errors early
4. Use defensive prompts - Ask for error handling
5. Maintain backups - External to git

Automated Recovery

Configure hooks for automatic recovery:

{
  "hooks": {
    "postToolUse": [
      {
        "match": "Error",
        "command": "git status && npm test"
      }
    ]
  }
}

Team Error Patterns

Document common errors in CLAUDE.md:

## Common Errors and Fixes

### Module Not Found
- Cause: Missing npm install
- Fix: Run `npm install` or check package.json

### Type Errors
- Cause: TypeScript strict mode
- Fix: Add proper type annotations

### Permission Denied
- Cause: File permissions
- Fix: Check ownership with `ls -la`

Emergency Recovery

When everything goes wrong:

1. Stop Claude: Press Esc or Ctrl+C
2. Assess damage: git status and git diff
3. Revert if needed: git checkout .
4. Check backups: Time Machine, snapshots, etc.
5. Start fresh: New terminal, new session
6. Report issues: If Claude bug, report to Anthropic

Caution

Always maintain backups outside of git for critical projects. Claude is powerful but not infallible.

Error Prevention Tips

Proactive Error Prevention

• Use containers for isolated environments
• Set up CI/CD to catch errors early
• Configure linters that Claude respects
• Document gotchas in CLAUDE.md
• Test in staging before production
• Use version control religiously

What’s Next?

You’ve completed the Claude Code quick-start guide! Here are your next steps:

Advanced Techniques Master expert-level Claude Code features

MCP Ecosystem Explore advanced MCP server configurations

Team Workflows Scale Claude Code across your organization

Remember: errors are learning opportunities. Each failure teaches Claude (and you) how to handle similar situations better in the future. Embrace the iterative process and build increasingly resilient workflows.