shield_lock
JinDaGe
← Back to skills
extension
Category: Development & EngineeringNo API key required

debugging-claude-code

Troubleshooting guide for Claude Code issues. Use when Claude behaves unexpectedly, tools fail, sessions hang, or you need to diagnose problems. Covers diagnostics, common issues, and recovery procedures.

personAuthor: jakexiaohubgithub
open_in_newRepositorydownloadDownload package

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

| Symptom | Likely Cause | Quick Fix | |---------|--------------|-----------| | Tool not working | Permission denied | /permissions then allow tool | | MCP tools missing | Server disconnected | /mcp to check status | | Hook not firing | JSON syntax error | jq . ~/.claude/settings.json | | Skill not loading | Invalid frontmatter | Check YAML syntax | | Context overflow | Too much data | Use /compact or /clear | | Rate limited | Too many requests | Wait 60 seconds | | API errors | Auth/network issues | Check ~/.claude/.credentials.json | | Session stuck | Process hanging | Ctrl+C, restart Claude | | Slow responses | Network or model load | Check connection, try again |

Debug Flags and Environment Variables

Command-Line Flags

| Flag | Purpose | |------|---------| | --debug | Enable verbose debug output | | --print-hooks | Display all registered hooks | | --verbose | Show more detailed output | | --no-cache | Disable response caching |

Environment Variables

| Variable | Purpose | Example | |----------|---------|---------| | ANTHROPIC_LOG | Log level | debug, info, warn, error | | CLAUDE_CODE_DEBUG | Additional debugging | 1 or true | | MCP_TIMEOUT | MCP connection timeout (ms) | 30000 | | MAX_MCP_OUTPUT_TOKENS | Max MCP output size | 50000 | | HTTP_PROXY | Proxy for network requests | http://proxy:8080 | | HTTPS_PROXY | HTTPS proxy | https://proxy:8080 | | NO_PROXY | Skip proxy for hosts | localhost,127.0.0.1 |

Combined Debug Session

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

Log Locations

By Operating System

| OS | Location | |----|----------| | macOS | ~/Library/Logs/Claude Code/ | | Linux | ~/.local/share/claude-code/logs/ | | Windows | %APPDATA%\Claude Code\logs\ |

Configuration Files

| File | Purpose | |------|---------| | ~/.claude/settings.json | User settings and hooks | | ~/.claude/.credentials.json | API credentials | | ~/.claude/projects.json | Project-specific settings | | .claude/settings.json | Project settings (committed) | | .claude/settings.local.json | Local project settings | | .mcp.json | MCP server configuration |

Session Data

| Location | Contents | |----------|----------| | ~/.claude/sessions/ | Session transcripts | | ~/.claude/todos/ | Task lists | | ~/.claude/memory/ | Persistent memory |

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

| Command | Purpose | |---------|---------| | /hooks | View registered hooks | | /mcp | MCP server status | | /permissions | Permission settings | | /memory | Memory bank status | | /status | Session status | | /bug | Report a bug | | /doctor | Run health checks |

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

| File | Contents | |------|----------| | DIAGNOSTICS.md | Detailed diagnostic techniques | | COMMON-ISSUES.md | Common problems and solutions | | RECOVERY.md | Recovery procedures |

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