Troubleshooting Guide

Reference · 15 min read

✓Common issues and solutions

Installation Issues

Permission Errors on macOS/Linux

npm install -g @anthropic-ai/claude-code
# Error: EACCES: permission denied

# Solution 1: Use sudo
sudo npm install -g @anthropic-ai/claude-code

# Solution 2: Fix npm permissions
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH

Command Not Found After Install

# Check installation
npm list -g @anthropic-ai/claude-code

# Verify PATH includes npm global bin
echo $PATH | grep npm

# For Bun users
bun install -g @anthropic-ai/claude-code

Authentication Issues

Login Fails

# Clear existing auth
rm -rf ~/.claude/settings.json

# Re-login
claude login

# Check for firewall blocking OAuth callback

API Key Not Working

# Verify key format
export ANTHROPIC_API_KEY="sk-ant-..."

# Test connection
claude --version

# Check for typos in key

Common Error Messages

"Rate limit exceeded"

You've hit your usage limit. Wait for reset or upgrade subscription.

# Check usage
/usage

# Switch to cheaper model
/model sonnet

"Model not available"

Opus requires Max subscription. Pro users can only use Sonnet.

"Tool execution failed"

Check tool permissions and file access rights.

Performance Issues

Slow Responses

  • Check network connection
  • Switch to Sonnet for faster responses
  • Clear context if conversation is too long

High Token Usage

  • Use specific file paths instead of broad searches
  • Clear conversation history periodically
  • Use Plan mode for read-only analysis

Debug Tools

Enable Verbose Mode

claude --verbose

Check System Status

/status
/doctor

View Logs

# Location varies by OS
# macOS: ~/Library/Logs/Claude
# Linux: ~/.local/share/Claude/logs
# Windows: %APPDATA%\Claude\logs
⚠️ When to Seek Help: If issues persist after trying these solutions, check the official documentation or community forums.