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
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
majiayu000