Build This Now
Build This Now
What Is Claude CodeInstallationNative InstallerFirst Project
speedy_devvkoen_salo
Blog/Handbook/Reference/Troubleshooting

Claude Code Troubleshooting

Five ordered checks for Claude Code breakage: install errors, bad API keys, 503 timeouts, slow replies, and permission trouble. Exact fixes for each path.

Want the framework behind these builds?

Get the Claude Code system we use to plan, build, test, and ship production software.

See what we build for companies →
speedy_devvkoen_salo
speedy_devvWritten by speedy_devvPublished Mar 11, 2026Handbook hubReference index

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:

  1. Sign out of Claude in your browser, fully
  2. Flush cookies and cached data
  3. Reopen a private window and log back in
  4. 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:

VariableWhat It Does
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFICKills auto-updates, telemetry, error reporting, and bug reports in one shot. Handy when chasing a network issue.
DISABLE_AUTOUPDATERTurns off auto-updates only. Set to 1 if update runs are breaking things.
DISABLE_ERROR_REPORTINGOpts out of Sentry error reporting (set to 1).
DISABLE_TELEMETRYOpts out of Statsig telemetry (set to 1).
CLAUDE_CODE_DISABLE_BACKGROUND_TASKSShuts 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.

Continue in Reference

  • Best SaaS Boilerplate 2026: The Honest Comparison
    An honest 2026 roundup of the best SaaS boilerplates and starter kits (ShipFast, Makerkit, Supastarter, SaaS Pegasus, Divjoy, open source), with real pricing, stacks, and the trade-off nobody mentions: a boilerplate still leaves you coding.
  • Claude Code Changelog
    Release-by-release notes for Claude Code from the v0.2 beta through March 2026. Bare mode, Channels permission relay, OAuth fixes, and every breaking change.
  • What It Really Costs to Build a SaaS MVP in 2026
    A buyer's cost breakdown for building a SaaS MVP in 2026. Real freelancer, agency, no-code, AI-tool, and DIY numbers with citations, plus where the money actually goes.
  • Prompt Templates That Ship Code
    Ten prompt recipes that ship code: full-stack scaffolding, APIs, schemas, tests, refactors, debugging, reviews, and CI. Each with failure modes to avoid.
  • Claude Code FAQ
    Straight answers on Claude Code pricing, daily spend, model choice, Cursor comparison, Skills, CLAUDE.md, API keys, and what the terminal agent can actually do.
  • Lovable Alternative for Production Apps (2026)
    Tried Lovable, v0, Bolt, or Replit Agent and hit a wall going to production? Here is an honest look at where AI app builders break, plus a production-grade alternative where you own the code, get real auth and payments, and ship with security built in.

More from Handbook

  • Deep Thinking Techniques
    Thinking trigger phrases like think harder, ultrathink, and think step by step push Claude Code into extended reasoning and more test-time compute, same model.
  • Efficiency Patterns
    Permutation frameworks turn 8 to 12 manual builds into a CLAUDE.md template Claude Code uses to generate variations 11, 12, and 13 on demand. Captured once.
  • Claude Code Fast Mode
    Fast mode routes your Opus 4.6 requests down a priority serving path in Claude Code. Same weights, same ceiling, replies 2.5x quicker at a higher token rate.
  • Speed Optimization
    Model selection, context size, and prompt specificity are the three levers that decide how fast Claude Code replies. /model haiku, /compact, and /clear covered.

Want the framework behind these builds?

Get the Claude Code system we use to plan, build, test, and ship production software.

See what we build for companies →
speedy_devvkoen_salo

On this page

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

Want the framework behind these builds?

Get the Claude Code system we use to plan, build, test, and ship production software.

See what we build for companies →