MCP

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.

90%
Issues Solved
50+
Commands
15+
Quick Fixes
100+
Community Tips

Quick Navigation

Permission Errors & Solutions

Permission denied / EACCES

File Access
Linux/macOSFix file ownership
sudo chown -R $(whoami) .
WindowsElevate permissions
Run Command Prompt as Administrator
AllAdd directory to allowed list
claude --add-dir /path/to/directory

Invalid API key

API Permission
AllReconfigure API key
claude config
AllCheck environment variable
echo $ANTHROPIC_API_KEY
AllForce clean login
rm ~/.claude/auth.json

Repeated permission prompts

Tool Permissions
AllAllow all bash commands (use carefully)
/permissions allow bash:*
AllAllow all file reads
/permissions allow Read:*
AllSkip all prompts (controlled environments only)
--dangerously-skip-permissions

Token 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.com

Test 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 REPL
claude "query"REPL with initial prompt
claude -p "query"One-shot query (automation)
cat file | claude -p "analyze"Pipe content for analysis
claude -cContinue last session
claude -r <id>Resume specific session

Configuration

claude configInteractive setup
claude config listView all settings
claude config set model sonnetSet project model
claude config set -g model opusSet global default

Advanced Flags

--output-format jsonJSON output for automation
--debugEnable debug logging
--mcp-debugDebug MCP connections
--dangerously-skip-permissionsSkip all prompts (careful!)
--thinkAllocate maximum reasoning

Slash Commands (In-Session)

Core

/helpShow all commands
/clearStart fresh (MOST IMPORTANT)
/statusSystem information
/costMonitor token usage & spending
/exitClean shutdown

Configuration

/configView/modify settings
/permissionsSecurity control
/doctorComplete health check

Session Management

/undoRevert last action
/compactCompress history, save tokens
/save <name>Create checkpoint
/load <name>Restore checkpoint

Memory & Context

/memory editModify CLAUDE.md
/memory viewCheck current context
/initCreate CLAUDE.md for project

Hidden Thinking Commands

think

~1,024 tokens

Basic analysis

claude "think about this function"

think hard

~5,000 tokens

Enhanced analysis

claude "think hard about the security implications"

think deeply

~10,000 tokens

Advanced research

claude "think deeply about the architecture"

ultrathink

128,000 tokens

Maximum analysis

claude "ultrathink about the entire system"

Keyboard Shortcuts

Essential

Ctrl+CCancel operation⚠️ Exits entirely in some contexts
EscapeStop Claude (preferred)
Ctrl+LClear display, keep history
↑/↓Navigate command history

Claude-Specific

Shift+TabAuto-accept mode (no confirmation)
Shift+Tab (2x)Planning mode (analyze only)
Escape (2x)Edit previous prompts

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

Interactive session list

claude --resume session-id

Resume specific session

claude --continue

Continue most recent

Session File Locations

~/.claude/sessions/- Session history
~/.claude/auth/- Auth tokens
~/.claude/cache/- Temporary cache

Safe 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
  • &quot;Saved me hours&quot; - User feedback

Update Lock Fix

Problem: &quot;Another instance is updating&quot; 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&apos;t let history eat tokens
  • Queue multiple commands
  • &quot;Most important optimization&quot; - 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.