Debugging Claude Code

Debugging Claude Code

Systematic troubleshooting guide for diagnosing and resolving Claude Code issues.

Quick Diagnostics

Run these commands first when experiencing issues:

# Health check - comprehensive system status
claude doctor

# Or in-session
/​doctor

# Check Claude Code version
claude --version

# Debug mode - verbose output for all operations
claude --debug

# Environment-level debug logging
ANTHROPIC_LOG=debug claude

# Check registered hooks
claude --print-hooks

# View MCP server status
claude mcp list

Common Issues Quick Reference

Debug Flags and Environment Variables

Command-Line Flags

Environment Variables

Combined Debug Session

# Maximum verbosity
ANTHROPIC_LOG=debug claude --debug 2>&1 | tee ~/​claude-debug.log

Log Locations

By Operating System

Configuration Files

Session Data

Diagnostic Commands

System Health

# Full health check
claude doctor

# Check component status
claude doctor --component api
claude doctor --component mcp
claude doctor --component hooks

/​doctor reports (2.1.6+):

• Updates section - Shows auto-update channel and available npm versions (stable/​latest)
• Permission warnings - Detects unreachable permission rules with fix guidance
• API connectivity - Verifies connection to Anthropic API
• MCP servers - Lists connected servers and their status
• Hooks - Validates hook configurations

Permission Diagnostics

# View current permissions
/​permissions

# Check what tools are allowed
/​permissions --tools

# Check file access patterns
/​permissions --files

Hook Diagnostics

# List all registered hooks
claude --print-hooks

# View hooks in interactive mode
/​hooks

# Validate hook JSON
jq . ~/​.claude/​settings.json
jq . .claude/​settings.json

MCP Diagnostics

# List configured servers
claude mcp list

# Get server details
claude mcp get <server-name>

# Check connection in session
/​mcp

Diagnostic Decision Tree

Is Claude starting?

Claude won't start
    |
    +-- Check: claude --version
    |   |
    |   +-- Works --> Config issue, check ~/​.claude/
    |   +-- Fails --> Installation issue, reinstall
    |
    +-- Check: ANTHROPIC_LOG=debug claude
        |
        +-- Auth error --> Check credentials
        +-- Network error --> Check connectivity
        +-- Other --> See COMMON-ISSUES.md

Are tools working?

Tool not working
    |
    +-- Check: /​permissions
    |   |
    |   +-- Denied --> Allow tool
    |   +-- Allowed --> Continue
    |
    +-- Check: --debug output
    |   |
    |   +-- Tool called --> Check tool-specific logs
    |   +-- Not called --> Check permissions/​syntax
    |
    +-- MCP tool?
        |
        +-- Yes --> /​mcp, check server status
        +-- No --> See COMMON-ISSUES.md

Are hooks working?

Hook not firing
    |
    +-- Check: /​hooks
    |   |
    |   +-- Listed --> Matcher issue or script issue
    |   +-- Not listed --> JSON syntax error
    |
    +-- Validate JSON: jq . settings.json
    |   |
    |   +-- Valid --> Check matcher pattern
    |   +-- Invalid --> Fix JSON syntax
    |
    +-- Test script: echo '{}' | ./​hook.sh
        |
        +-- Works --> Matcher doesn't match
        +-- Fails --> Script error

Built-in Diagnostic Commands

Verbose Mode

Toggle verbose mode during a session:

• Keyboard shortcut: Ctrl+O (in terminal)
• Shows: Hook execution, tool calls, API responses

Quick Fixes

Permission Issues

# Allow all file operations in project
/​permissions --allow "Write,Edit,Read" --scope project

# Allow specific MCP server
/​permissions --allow "mcp__servername__*"

Clear Issues

# Clear conversation context
/​clear

# Compact context (keep important parts)
/​compact

# Reset session
/​reset

Configuration Reset

# Back up and reset settings
cp ~/​.claude/​settings.json ~/​.claude/​settings.json.bak
rm ~/​.claude/​settings.json

# Reset just hooks
jq 'del(.hooks)' ~/​.claude/​settings.json > tmp && mv tmp ~/​.claude/​settings.json

Reference Files

When to Escalate

Use /​bug to report issues when:

• claude doctor shows failures
• Reproducible crashes
• API errors persist after credential refresh
• Behavior contradicts documentation

Include in bug reports:

• Claude Code version (claude --version)
• OS and version
• Debug output (claude --debug)
• Steps to reproduce