Claude-skill-registry 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.

install

source · Clone the upstream repo

git clone https://github.com/majiayu000/claude-skill-registry

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/majiayu000/claude-skill-registry "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/data/debugging-claude-code" ~/.claude/skills/majiayu000-claude-skill-registry-debugging-claude-code && rm -rf "$T"

manifest: skills/data/debugging-claude-code/SKILL.md

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