Claude Code Troubleshooting & Commands
Comprehensive troubleshooting guide and command reference for Claude Code. Based on extensive research from official documentation, GitHub issues, and real user experiences through 2024-2025.
Quick Navigation
Permission Errors & Solutions
Permission denied / EACCES
File Accesssudo chown -R $(whoami) .Run Command Prompt as Administratorclaude --add-dir /path/to/directoryInvalid API key
API Permissionclaude configecho $ANTHROPIC_API_KEYrm ~/.claude/auth.jsonRepeated permission prompts
Tool Permissions/permissions allow bash:*/permissions allow Read:*--dangerously-skip-permissionsToken Limit Errors
429 Rate Limit - Exponential Backoff
async function callClaudeWithRetry(payload, maxRetries = 5) {
let retries = 0;
while (retries < maxRetries) {
try {
const response = await axios.post(CLAUDE_API_URL, payload);
return response.data;
} catch (error) {
if (error.response?.status === 429) {
const retryAfter = error.response.headers['retry-after']
|| Math.pow(2, retries) * 1000;
await new Promise(resolve => setTimeout(resolve, retryAfter));
retries++;
} else {
throw error;
}
}
}
}Context Window Overflow (400 Error)
- Use /compact with specific instructions
- Start fresh with /clear (most important command)
- Break large files into smaller components
- Work on one feature at a time
- Clear after every major task completion
Pro Tip: Use /clear after every major task - it's the most important command according to power users.
Connection Errors
WSL Terminal Connection Error
"API Error: Connection error" - Cloudflare blocking terminal requests
curl -v https://api.anthropic.comTest connectivity, then switch to browser interface if blocked
503 Service Unavailable
"503 no healthy upstream" - Server-side issue
- • Wait 2-5 minutes for recovery
- • Check status.anthropic.com
- • Don't reinstall (won't help)
CLI Commands Reference
Core Commands
claudeStart interactive REPLclaude "query"REPL with initial promptclaude -p "query"One-shot query (automation)cat file | claude -p "analyze"Pipe content for analysisclaude -cContinue last sessionclaude -r <id>Resume specific sessionConfiguration
claude configInteractive setupclaude config listView all settingsclaude config set model sonnetSet project modelclaude config set -g model opusSet global defaultAdvanced Flags
--output-format jsonJSON output for automation--debugEnable debug logging--mcp-debugDebug MCP connections--dangerously-skip-permissionsSkip all prompts (careful!)--thinkAllocate maximum reasoningSlash Commands (In-Session)
Core
/helpShow all commands★/clearStart fresh (MOST IMPORTANT)★/statusSystem information/costMonitor token usage & spending★/exitClean shutdownConfiguration
/configView/modify settings/permissionsSecurity control/doctorComplete health checkSession Management
/undoRevert last action/compactCompress history, save tokens/save <name>Create checkpoint/load <name>Restore checkpointMemory & Context
/memory editModify CLAUDE.md/memory viewCheck current context/initCreate CLAUDE.md for projectHidden Thinking Commands
think
~1,024 tokensBasic analysis
claude "think about this function"think hard
~5,000 tokensEnhanced analysis
claude "think hard about the security implications"think deeply
~10,000 tokensAdvanced research
claude "think deeply about the architecture"ultrathink
128,000 tokensMaximum analysis
claude "ultrathink about the entire system"Keyboard Shortcuts
Essential
Claude-Specific
Emergency Recovery Procedures
Simple context issues
/clear- Clears context window completely
- Preserves session & CLAUDE.md
- Faster than full restart
- No reinitialization cost
Session corruption / infinite loops
Full restart- Use Escape (not Ctrl+C)
- Restart with 'claude'
- Required after major config changes
- Needed when switching projects
Force termination
Process-specific kill- ps aux | grep "claude\|@anthropic-ai"
- kill -TERM <pid> (graceful)
- kill -KILL <pid> (force)
- NEVER use pkill node or killall node
Critical Warning
NEVER use pkill node or killall node - these will terminate Claude Code AND VS Code/other Node apps, causing data loss. Always use process-specific kills targeting exact PIDs.
Session Recovery
Resume Recent Sessions
claude --resumeInteractive session list
claude --resume session-idResume specific session
claude --continueContinue most recent
Session File Locations
~/.claude/sessions/- Session history~/.claude/auth/- Auth tokens~/.claude/cache/- Temporary cacheSafe to delete for clean reset: auth/, sessions/, cache/
Community Solutions & Workarounds
WSL Image Pasting Fix
Problem: Can't paste images from Windows clipboard
Solution: WSL Paste Workaround Script
- • Captures via Shift+Insert
- • Saves to shared folder
- • Auto-pastes @sharedclaude/filename.png
- • "Saved me hours" - User feedback
Update Lock Fix
Problem: "Another instance is updating" when none exists
Solution: UpdateFix.sh script
- • Cleans stuck update locks
- • Runs Claude update
- • Removes outdated binaries
- • Refreshes shell cache
Context Management Strategy
Problem: Claude becomes less effective over time
Solution: Aggressive /clear usage
- • Clear after EVERY major task
- • Don't let history eat tokens
- • Queue multiple commands
- • "Most important optimization" - Power users
Best Practices from Heavy Users
Task Management
Break complex tasks into smaller problems
One user: "2 days arguing on complex PR ($100) vs two 10-minute tasks"
Handle Git operations manually
Let Claude modify files, you handle commits
Performance Tips
Claude handles large files better than competitors
"18,000-line React component - only Claude Code succeeded"
Monitor usage with /cost and /status
Set up ccundo for checkpoints before major operations
Platform-Specific Optimizations
WSL Users
- • Store files in Linux filesystem (/home/ not /mnt/c/)
- • Configure .wslconfig with 8GB memory, 4 processors
- • Use WSL Paste Workaround for images
macOS Users
- • Grant Terminal full disk access in System Preferences
- • Install Node via nodejs.org (not Homebrew)
- • Use Escape key, not Ctrl+C for stopping
Master Claude Code Today
This comprehensive guide represents the collective knowledge of the Claude Code community through 2024-2025. These solutions, commands, and workarounds will help you work more efficiently and recover quickly from any issues.