Claude Code Troubleshooting: Fix Common Issues Fast

Claude Code not working? Here's the fix: 90% of issues are solved by these five quick checks. Run them in order, and you'll be back to coding in minutes.

Quick diagnosis checklist:

# 1. Check your installation
claude --version
 
# 2. Test your internet connection
ping claude.ai
 
# 3. Verify your API key
echo $ANTHROPIC_API_KEY
 
# 4. Clear session state
claude /clear
 
# 5. Restart with fresh config
claude config

If any command fails, jump to the matching section below for the exact fix.

Installation Problems

Error: "command not found: claude"

Your installation failed or PATH isn't configured. Fix it now:

# Reinstall globally
npm install -g @anthropic-ai/claude-code
 
# Verify installation
which claude

Error: "Node.js version not supported"

Claude Code requires Node.js 18+. Check your version:

# Check current version
node --version
 
# If below 18.0, install latest Node.js
# Visit nodejs.org and download the LTS version

Error: "EACCES permission denied"

Fix npm permissions on macOS/Linux:

# Fix npm ownership
sudo chown -R $(whoami) ~/.npm
 
# Alternative: use a version manager like nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

For Windows, run Command Prompt as Administrator and retry installation.

Authentication Issues

Error: "Invalid API key"

Your API key is missing or incorrect. Set it properly:

# Reconfigure Claude Code
claude config
 
# Or set environment variable
export ANTHROPIC_API_KEY="your-api-key-here"

Get your API key from console.anthropic.com and ensure no extra spaces.

Error: "Subscription not recognized"

Claude Max/Pro authentication problems:

1. Log out of Claude completely in your browser
2. Clear cookies and browser cache
3. Use incognito/private mode to log back in
4. Run claude config to re-authenticate

Connection Problems

Error: "503 Service Unavailable"

This is a server-side issue, not your setup:

• Wait 2-5 minutes for Anthropic servers to recover
• Check status.anthropic.com for updates
• Don't reinstall - this won't fix server problems

Claude Code starts but doesn't respond

Reset your session state:

# Clear conversation history
claude /clear
 
# Restart with fresh session
exit
claude

If still unresponsive, check your internet connection and try again.

Performance Issues

Slow responses or hanging

Switch to a faster model and optimize context:

# Use Claude 4 Sonnet for speed
claude --model claude-sonnet-4-20250514
 
# Compress conversation history
claude /compact keep only function names and current errors

"Context window full" errors

Your conversation is too long. Reset or compress:

# Quick fix: start fresh
claude /clear
 
# Better fix: compress intelligently
claude /compact preserve main components and recent changes only

File Permission Errors

Error: "Permission denied on file operations"

Fix directory permissions:

# Check current permissions
ls -la
 
# Fix ownership of project directory
sudo chown -R $(whoami) .
 
# Verify Claude Code can access files
claude --add-dir $(pwd)

Advanced Fixes

Nothing else worked? Complete reset:

# 1. Uninstall completely
npm uninstall -g @anthropic-ai/claude-code
 
# 2. Remove config files
rm ~/.claude.json
rm -rf ~/.claude/
 
# 3. Clear npm cache
npm cache clean --force
 
# 4. Fresh install
npm install -g @anthropic-ai/claude-code
claude config

Success Verification

After fixing issues, verify everything works:

# Test basic functionality
claude "write hello world in Python"
 
# Test file operations
echo "# Test" > test.md
claude "read and improve test.md"
 
# Test context management
claude /help

Your Claude Code should now respond normally. If problems persist, the issue may be service-side - check status.anthropic.com for updates.

Next Steps

Now that Claude Code is working:

• Set up your first project properly
• Learn context management to avoid future issues
• Configure optimal settings for your workflow
• Check our installation guide for platform-specific tips
• Review common errors to prevent future problems