22  Troubleshooting

Common issues and how to fix them.

22.1 Installation Issues

22.1.1 Claude Code Won’t Install

Error: “npm not found”

Node.js isn’t installed. Install it:

# Mac
brew install node

# Or download from nodejs.org

Error: “EACCES permission denied”

npm needs permissions. Fix with:

# Option 1: Fix permissions
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# Option 2: Use sudo (not recommended but works)
sudo npm install -g @anthropic-ai/claude-code

Error: “Node version too old”

Update Node:

# Mac
brew upgrade node

# Or use nvm
nvm install --lts
nvm use --lts

22.1.2 Claude Code Won’t Start

Error: “claude: command not found”

The binary isn’t in PATH. Try:

# Find where it installed
npm list -g @anthropic-ai/claude-code

# Add to PATH or reinstall

Error: “Authentication failed”

Re-authenticate:

# Clear existing credentials
rm -rf ~/.claude

# Restart and re-auth
claude

22.2 Authentication Issues

22.2.1 API Key Not Working

  1. Check the key is correct (no extra spaces)
  2. Verify the key is active in console.anthropic.com
  3. Check for billing issues

22.2.2 “Rate limited” Errors

You’re making too many requests. Solutions: - Wait and try again - Check your usage limits - Reduce request frequency

22.2.3 Session Expired

Re-authenticate:

claude logout
claude login

22.3 GitHub Issues

22.3.1 “Permission denied (publickey)”

SSH key isn’t set up. See GitHub Setup.

Quick fix:

# Check SSH agent
ssh-add -l

# Add your key
ssh-add ~/.ssh/id_ed25519

# Test
ssh -T git@github.com

22.3.2 “Repository not found”

  • Check the URL is correct
  • Ensure you have access (if private)
  • Try HTTPS instead of SSH

22.3.3 “Support for password authentication was removed”

Use SSH or a Personal Access Token instead of password.

22.4 Common Runtime Errors

22.4.1 “Context window exceeded”

The conversation is too long. Solutions: - Start a new session - Work with smaller files - Be more focused in requests

22.4.2 “Tool execution failed”

Usually a permissions or path issue: - Check file permissions - Verify paths exist - Check working directory

22.4.3 Commands Hang

Press Ctrl + C to cancel. Then: - Check if the command makes sense - Try running it manually to debug - Add timeout if appropriate

22.5 File and Path Issues

22.5.1 “File not found”

  • Check the path is correct
  • Use absolute paths if needed
  • Verify you’re in the right directory

22.5.2 “Permission denied” on Files

# Check permissions
ls -la filename

# Fix if needed
chmod 644 filename  # for files
chmod 755 directory # for directories

22.5.3 Encoding Issues

If files have weird characters:

# Check encoding
file filename

# Convert if needed
iconv -f ISO-8859-1 -t UTF-8 input.txt > output.txt

22.6 Platform-Specific Issues

22.6.1 Mac

“developer cannot be verified” - Right-click → Open, then click Open - Or: System Preferences → Security → Allow

Homebrew issues

brew update
brew doctor

22.6.2 Windows

Line ending issues Configure git:

git config --global core.autocrlf true

PowerShell execution policy

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

22.6.3 Linux

Missing libraries Install build essentials:

sudo apt-get install build-essential

22.7 When Nothing Works

22.7.1 Full Reset

# 1. Uninstall
npm uninstall -g @anthropic-ai/claude-code

# 2. Clear config
rm -rf ~/.claude

# 3. Reinstall
npm install -g @anthropic-ai/claude-code

# 4. Re-authenticate
claude

22.7.2 Getting Help

  1. Check official docs: claude.ai/docs
  2. Search GitHub issues: github.com/anthropics/claude-code/issues
  3. Ask with details:
    • Operating system and version
    • Error message (full)
    • What you were trying to do
    • What you already tried