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.
Diagnoses Claude Code issues with health checks, debug commands, and troubleshooting guides for tools, hooks, and MCP servers.
/plugin marketplace add hgeldenhuys/claude-code-sdk/plugin install hgeldenhuys-session-naming@hgeldenhuys/claude-code-sdkThis skill is limited to using the following tools:
COMMON-ISSUES.mdDIAGNOSTICS.mdRECOVERY.mdSystematic troubleshooting guide for diagnosing and resolving Claude Code issues.
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
| 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 |
| Flag | Purpose |
|---|---|
--debug | Enable verbose debug output |
--print-hooks | Display all registered hooks |
--verbose | Show more detailed output |
--no-cache | Disable response caching |
| 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 |
# Maximum verbosity
ANTHROPIC_LOG=debug claude --debug 2>&1 | tee ~/claude-debug.log
| OS | Location |
|---|---|
| macOS | ~/Library/Logs/Claude Code/ |
| Linux | ~/.local/share/claude-code/logs/ |
| Windows | %APPDATA%\Claude Code\logs\ |
| 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 |
| Location | Contents |
|---|---|
~/.claude/sessions/ | Session transcripts |
~/.claude/todos/ | Task lists |
~/.claude/memory/ | Persistent memory |
# 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+):
# View current permissions
/permissions
# Check what tools are allowed
/permissions --tools
# Check file access patterns
/permissions --files
# List all registered hooks
claude --print-hooks
# View hooks in interactive mode
/hooks
# Validate hook JSON
jq . ~/.claude/settings.json
jq . .claude/settings.json
# List configured servers
claude mcp list
# Get server details
claude mcp get <server-name>
# Check connection in session
/mcp
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
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
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
| 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 |
Toggle verbose mode during a session:
Ctrl+O (in terminal)# Allow all file operations in project
/permissions --allow "Write,Edit,Read" --scope project
# Allow specific MCP server
/permissions --allow "mcp__servername__*"
# Clear conversation context
/clear
# Compact context (keep important parts)
/compact
# Reset session
/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
| File | Contents |
|---|---|
| DIAGNOSTICS.md | Detailed diagnostic techniques |
| COMMON-ISSUES.md | Common problems and solutions |
| RECOVERY.md | Recovery procedures |
Use /bug to report issues when:
claude doctor shows failuresInclude in bug reports:
claude --version)claude --debug)Creating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems. Create original algorithmic art rather than copying existing artists' work to avoid copyright violations.
Applies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.
Create beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations.