Claude Code Troubleshooting

Resolve install errors, bad API keys, 503 timeouts, slow replies, and permission trouble. Five ordered checks clear the common breakage paths.

Problem. Claude Code stopped working and you don't know why. Most breakage comes from five places, and a short checklist sorts them out. Walk the list in order and you'll be typing prompts again within a few 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 (inside Claude Code)
/clear
 
# 5. Restart with fresh config
claude config

If one of those commands blows up, skip to the matching section for the exact fix.

Installation Problems

Error. command not found: claude

The binary never landed on your PATH, or the install failed outright. The native installer sorts this out on its own:

# Reinstall with native installer (recommended)
curl -fsSL https://claude.ai/install.sh | bash  # macOS/Linux
# Windows PowerShell: irm https://claude.ai/install.ps1 | iex
 
# Verify installation
which claude

Error. Node.js version not supported

Node 18 or higher is the floor. Check what you have:

# 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

On macOS and Linux, npm ownership is the usual culprit:

# 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

On Windows, open Command Prompt as Administrator and run the installer again.

Authentication Issues

Error. Invalid API key

Either your key is unset or it's wrong. Set it cleanly:

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

Grab a fresh key at console.anthropic.com. Watch for stray spaces on paste.

Error. Subscription not recognized

For Max and Pro auth failures:

Sign out of Claude in your browser, fully
Flush cookies and cached data
Reopen a private window and log back in
Re-run claude config to finish the handshake

Connection Problems

Error. 503 Service Unavailable

That's on Anthropic's side, not yours:

Give it 2 to 5 minutes and the servers usually recover
status.anthropic.com will confirm if something is down
Reinstalling won't help a server problem

Claude Code launches but goes silent

Wipe the session state:

# Clear conversation history (run inside Claude Code)
/clear
 
# Or restart with fresh session
exit
claude

Still nothing? Confirm your connection is alive and retry.

Performance Issues

Slow responses or hanging

Pick a quicker model and trim the context:

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

Error. Context window full

The thread grew too big. Reset it or compress it:

# Quick fix: start fresh (run inside Claude Code)
/clear
 
# Better fix: compress intelligently
/compact preserve main components and recent changes only

File Permission Errors

Error. Permission denied on file operations

Directory ownership is off. Fix it:

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

Settings and Configuration Issues

Settings behaving strangely

Nine times out of ten, scope precedence is the reason. The order runs Managed > Command line > Local > Project > User. So a key in .claude/settings.local.json beats the same key in .claude/settings.json, which in turn beats ~/.claude/settings.json.

# Check which settings files exist
ls ~/.claude/settings.json
ls .claude/settings.json
ls .claude/settings.local.json

Managed settings overriding your preferences

If IT pushed a managed-settings.json, it sits at the top of the stack and you can't override it. Managed files live at /Library/Application Support/ClaudeCode/ on macOS, /etc/claude-code/ on Linux and WSL, and C:\Program Files\ClaudeCode\ on Windows. If one setting keeps snapping back, ask your admin whether a policy is pinning it.

Settings autocomplete not working

Drop a $schema line at the top of your settings.json so the editor can validate and autocomplete:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json"
}

Sandbox and Security Issues

Error. bubblewrap not installed (Linux/WSL2)

Linux sandboxing depends on the bubblewrap and socat packages. Install both and rerun:

# Debian/Ubuntu
sudo apt install bubblewrap socat
 
# Fedora
sudo dnf install bubblewrap socat

Watchman conflicts with sandbox

Meta's Watchman file watcher fights with the Claude Code sandbox. Turn Watchman off, or keep it outside the sandbox boundary.

Docker commands failing inside sandbox

Docker has to run outside the sandbox. Put it in excludedCommands inside settings.json:

{
  "sandbox": {
    "enabled": true,
    "excludedCommands": ["docker", "docker-compose"]
  }
}

Debug Environment Variables

Stuck on a stubborn bug? These env vars help you split the problem apart:

Variable	What It Does
`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`	Kills auto-updates, telemetry, error reporting, and bug reports in one shot. Handy when chasing a network issue.
`DISABLE_AUTOUPDATER`	Turns off auto-updates only. Set to `1` if update runs are breaking things.
`DISABLE_ERROR_REPORTING`	Opts out of Sentry error reporting (set to `1`).
`DISABLE_TELEMETRY`	Opts out of Statsig telemetry (set to `1`).
`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS`	Shuts off every background task (set to `1`).

# Run Claude Code with all non-essential traffic disabled
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 claude
 
# Or set just the auto-updater off
DISABLE_AUTOUPDATER=1 claude

Think it's a proxy or network thing? Route traffic with HTTP_PROXY or HTTPS_PROXY, and use NO_PROXY to skip the proxy for specific hosts.

Advanced Fixes

Still broken? Nuke it and start over:

# 1. Uninstall any existing installation
npm uninstall -g @anthropic-ai/claude-code  # if installed via npm
 
# 2. Remove config files
rm ~/.claude.json
rm -rf ~/.claude/
 
# 3. Fresh install with native installer (recommended)
curl -fsSL https://claude.ai/install.sh | bash  # macOS/Linux
# Windows PowerShell: irm https://claude.ai/install.ps1 | iex
 
# 4. Reconfigure
claude config

The native installer wires up PATH on its own and keeps itself updated.

Success Verification

Once the fix is in, run a quick sanity check:

# Test basic functionality
claude "write hello world in Python"
 
# Test file operations
echo "# Test" > test.md
claude "read and improve test.md"
 
# Test help command (inside Claude Code)
/help

Claude Code should be replying normally now. If it still isn't, the problem is probably service-side. Wait a few minutes. Try again.

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 (inside Claude Code)
/clear
 
# 5. Restart with fresh config
claude config

If one of those commands blows up, skip to the matching section for the exact fix.

Installation Problems

Error. command not found: claude

The binary never landed on your PATH, or the install failed outright. The native installer sorts this out on its own:

# Reinstall with native installer (recommended)
curl -fsSL https://claude.ai/install.sh | bash  # macOS/Linux
# Windows PowerShell: irm https://claude.ai/install.ps1 | iex
 
# Verify installation
which claude

Error. Node.js version not supported

Node 18 or higher is the floor. Check what you have:

# 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

On macOS and Linux, npm ownership is the usual culprit:

# 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

On Windows, open Command Prompt as Administrator and run the installer again.

Authentication Issues

Error. Invalid API key

Either your key is unset or it's wrong. Set it cleanly:

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

Grab a fresh key at console.anthropic.com. Watch for stray spaces on paste.

Error. Subscription not recognized

For Max and Pro auth failures:

Sign out of Claude in your browser, fully
Flush cookies and cached data
Reopen a private window and log back in
Re-run claude config to finish the handshake

Connection Problems

Error. 503 Service Unavailable

That's on Anthropic's side, not yours:

Give it 2 to 5 minutes and the servers usually recover
status.anthropic.com will confirm if something is down
Reinstalling won't help a server problem

Claude Code launches but goes silent

Wipe the session state:

# Clear conversation history (run inside Claude Code)
/clear
 
# Or restart with fresh session
exit
claude

Still nothing? Confirm your connection is alive and retry.

Performance Issues

Slow responses or hanging

Pick a quicker model and trim the context:

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

Error. Context window full

The thread grew too big. Reset it or compress it:

# Quick fix: start fresh (run inside Claude Code)
/clear
 
# Better fix: compress intelligently
/compact preserve main components and recent changes only

File Permission Errors

Error. Permission denied on file operations

Directory ownership is off. Fix it:

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

Settings and Configuration Issues

Settings behaving strangely

# Check which settings files exist
ls ~/.claude/settings.json
ls .claude/settings.json
ls .claude/settings.local.json

Managed settings overriding your preferences

Settings autocomplete not working

Drop a $schema line at the top of your settings.json so the editor can validate and autocomplete:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json"
}

Sandbox and Security Issues

Error. bubblewrap not installed (Linux/WSL2)

Linux sandboxing depends on the bubblewrap and socat packages. Install both and rerun:

# Debian/Ubuntu
sudo apt install bubblewrap socat
 
# Fedora
sudo dnf install bubblewrap socat

Watchman conflicts with sandbox

Meta's Watchman file watcher fights with the Claude Code sandbox. Turn Watchman off, or keep it outside the sandbox boundary.

Docker commands failing inside sandbox

Docker has to run outside the sandbox. Put it in excludedCommands inside settings.json:

{
  "sandbox": {
    "enabled": true,
    "excludedCommands": ["docker", "docker-compose"]
  }
}

Debug Environment Variables

Stuck on a stubborn bug? These env vars help you split the problem apart:

Variable	What It Does
`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`	Kills auto-updates, telemetry, error reporting, and bug reports in one shot. Handy when chasing a network issue.
`DISABLE_AUTOUPDATER`	Turns off auto-updates only. Set to `1` if update runs are breaking things.
`DISABLE_ERROR_REPORTING`	Opts out of Sentry error reporting (set to `1`).
`DISABLE_TELEMETRY`	Opts out of Statsig telemetry (set to `1`).
`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS`	Shuts off every background task (set to `1`).

# Run Claude Code with all non-essential traffic disabled
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 claude
 
# Or set just the auto-updater off
DISABLE_AUTOUPDATER=1 claude

Think it's a proxy or network thing? Route traffic with HTTP_PROXY or HTTPS_PROXY, and use NO_PROXY to skip the proxy for specific hosts.

Advanced Fixes

Still broken? Nuke it and start over:

# 1. Uninstall any existing installation
npm uninstall -g @anthropic-ai/claude-code  # if installed via npm
 
# 2. Remove config files
rm ~/.claude.json
rm -rf ~/.claude/
 
# 3. Fresh install with native installer (recommended)
curl -fsSL https://claude.ai/install.sh | bash  # macOS/Linux
# Windows PowerShell: irm https://claude.ai/install.ps1 | iex
 
# 4. Reconfigure
claude config

The native installer wires up PATH on its own and keeps itself updated.

Success Verification

Once the fix is in, run a quick sanity check:

# Test basic functionality
claude "write hello world in Python"
 
# Test file operations
echo "# Test" > test.md
claude "read and improve test.md"
 
# Test help command (inside Claude Code)
/help

Claude Code should be replying normally now. If it still isn't, the problem is probably service-side. Wait a few minutes. Try again.

Claude Code Troubleshooting

Installation Problems

Authentication Issues

Connection Problems

Performance Issues

File Permission Errors

Settings and Configuration Issues

Sandbox and Security Issues

Debug Environment Variables

Advanced Fixes

Success Verification

On this page

Claude Code Troubleshooting

Installation Problems

Authentication Issues

Connection Problems

Performance Issues

File Permission Errors

Settings and Configuration Issues

Sandbox and Security Issues

Debug Environment Variables

Advanced Fixes

Success Verification

On this page