Agent-Skills.md

Agent Skills: 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.

UncategorizedID: hgeldenhuys/claude-code-sdk/debugging-claude-code

Repository

hgeldenhuys/claude-code-sdk
hgeldenhuys
1

Skill Files

Browse the full folder contents for debugging-claude-code.

Download Skill

Loading file tree…

skills/debugging-claude-code/SKILL.md

Skill Metadata

Name
debugging-claude-code
Description
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.

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