Most Claude Code failures fall into three buckets: installation problems, authentication errors, or environment-specific conflicts. Run claude doctor first — it auto-diagnoses the majority of issues in seconds. If Claude Code won't start at all, skip to the installation section below.
You install Claude Code, npm says success, but claude returns "command not found" — it's one of the most common complaints on Reddit and GitHub Issues. From auth errors to WSL path conflicts to context window crashes, this guide covers the fixes for every major failure pattern.
What Should I Do First When Claude Code Won't Start?
Before diving into specific fixes, check whether Claude Code itself can diagnose the problem.
claude doctor
This command automatically checks:
- Node.js version compatibility
- Authentication token validity
- Network connectivity
- Configuration file integrity (JSON validation)
- MCP server configuration errors
Any ✗ in the output points directly to the root cause. Copy the error message verbatim and search it — someone has almost certainly solved it before.
If claude itself won't start, doctor isn't available. Treat it as an installation problem and move to the next section.
One more thing worth checking early: Anthropic's status page. If the API is experiencing an outage, no amount of local troubleshooting will help.
How Do I Fix Claude Code Installation Failures?
Use the Native Installer (Recommended)
Before fighting npm issues, consider switching to the native installer. Since late 2025, Anthropic recommends this method over npm — it's a self-contained executable with zero dependencies (no Node.js, no npm required) and auto-updates in the background.
# macOS / Linux
curl -fsSL https://claude.ai/install.sh | bash
# Windows (PowerShell)
irm https://claude.ai/install.ps1 | iex
After installation, verify with claude --version. If you're migrating from an existing npm install, uninstall the npm version first to avoid conflicts:
npm uninstall -g @anthropic-ai/claude-code
curl -fsSL https://claude.ai/install.sh | bash
The native installer eliminates most of the npm-related issues described below. If you still need the npm method (CI pipelines, corporate environments with restricted curl access, etc.), read on.
Pattern 1: npm Global Install Permission Error
npm warn logfile Error: EACCES: permission denied
This happens when npm can't write to the global directory. sudo npm install -g works as a quick fix, but it tends to create other permission headaches down the line. The cleaner approach is to move npm's global directory into your home folder.
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g @anthropic-ai/claude-code
Pattern 2: Outdated Node.js Version
Claude Code requires Node.js 18 or higher. Check your version first.
node --version
If you're below 18, switch with nvm.
# Install or update nvm (v0.40.4 as of March 2026)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash
source ~/.bashrc
nvm install 22
nvm use 22
nvm alias default 22
Pattern 3: npm install Hangs
Common in proxy environments or corporate networks. Add --verbose to see where the process gets stuck.
npm install -g @anthropic-ai/claude-code --verbose
If it's a timeout, increase npm's fetch timeout.
npm config set fetch-timeout 600000
Pattern 4: Corporate Proxy or Firewall Blocks
Behind a corporate proxy, npm and Claude Code may fail to reach external servers. Set the proxy configuration for npm, and if your company uses a custom CA certificate, tell Node.js about it.
# Set npm proxy
npm config set proxy http://proxy.company.com:8080
npm config set https-proxy http://proxy.company.com:8080
# If your company uses a custom CA certificate
export NODE_EXTRA_CA_CERTS=/path/to/company-ca.crt
Add the NODE_EXTRA_CA_CERTS line to .bashrc to make it permanent.
Pattern 5: Multiple Installation Conflicts
If you've installed Claude Code multiple times (globally, locally, via different Node versions), conflicting versions can cause strange behavior.
# Check for multiple installations
which -a claude
npm ls -g @anthropic-ai/claude-code
# Clean slate: remove and reinstall
npm uninstall -g @anthropic-ai/claude-code
npm install -g @anthropic-ai/claude-code
Why Am I Getting 401 or 403 Authentication Errors?
Authentication errors are the first wall most people hit after a successful install.
401 Unauthorized: The API key is invalid or expired. Check your key in the Anthropic Console.
403 Forbidden: Your plan doesn't include Claude Code access, or the API key lacks required permissions.
Claude Code is available on these plans:
- Pro ($20/month) — includes Claude Code
- Max 5x ($100/month) — full Claude Code access
- Max 20x ($200/month) — full Claude Code access
- Team Premium ($150/person/month) — includes Claude Code
- API key — direct billing via the Anthropic Console
To reset authentication:
# Remove existing credentials
claude auth logout
# Re-authenticate
claude auth login
If the browser doesn't open automatically (common in remote/headless environments), press c to copy the OAuth URL and paste it manually. Alternatively, set the API key directly as an environment variable.
export ANTHROPIC_API_KEY="sk-ant-..."
Add it to .bashrc or .zshrc to make it permanent.
echo 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.bashrc
source ~/.bashrc
If 403 persists after re-authentication, try claude auth status to verify your current auth state. If everything looks correct on your end, contact Anthropic support.
What Causes Claude Code to Fail in WSL?
WSL (Windows Subsystem for Linux) introduces its own set of problems. If you're running Claude Code on WSL2, the following issues come up frequently in GitHub Issues and community forums.
Windows npm Bleeding into WSL
Run which npm inside WSL. If the path starts with /mnt/c/..., you're calling the Windows-side npm — not the Linux one. Install Node.js separately inside WSL.
# Install nvm inside WSL (v0.40.4 as of March 2026)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash
source ~/.bashrc
nvm install 22
nvm use 22
Browser Authentication Not Opening
claude auth login tries to open a browser, but WSL often can't launch the default browser. When this happens, press c to copy the OAuth URL to your clipboard, then paste it into your Windows browser manually.
Alternatively, set the API key directly via environment variable (see authentication section above).
File Path and Performance Issues
Working with files on the Windows side (/mnt/c/...) from WSL causes major performance degradation. Keep your Claude Code projects inside the WSL filesystem (~/) for best results.
# Good: WSL native filesystem
cd ~/projects/my-app
# Slow: Windows filesystem mounted in WSL
cd /mnt/c/Users/username/projects/my-app
For a deeper dive into WSL-specific connection problems, see Fix WSL2 Claude Code Disconnects.
Sandbox Setup on WSL2
Claude Code's sandbox feature requires bubblewrap and socat on WSL2. If you see sandbox-related errors:
sudo apt install bubblewrap socat
Switching to Windows Native
If WSL issues refuse to budge, Claude Code does run natively on Windows via PowerShell. But for most development work, WSL is the better environment once properly set up. Only fall back to native Windows if you're truly stuck.
# PowerShell
npm install -g @anthropic-ai/claude-code
What About macOS-Specific Issues?
macOS generally has fewer issues than WSL, but there are a couple of gotchas.
Homebrew Node.js Conflicts
If you installed Node.js via Homebrew and also have nvm, the two can conflict. Check which node is active:
which node
# Homebrew: /opt/homebrew/bin/node
# nvm: /Users/username/.nvm/versions/node/v22.x.x/bin/node
Pick one and stick with it. If using nvm, make sure Homebrew's Node isn't shadowing it:
brew uninstall node
Keychain / Credential Issues
On macOS, Claude Code may store credentials in the system Keychain. If authentication behaves strangely after an OS update or password change, reset the stored credentials:
claude auth logout
claude auth login
If that doesn't work, check Keychain Access (in Applications > Utilities) for any Claude-related entries and remove them manually before logging in again.
Apple Silicon (M1/M2/M3/M4) Compatibility
Claude Code runs natively on Apple Silicon — no Rosetta needed. If you're using the native installer, it handles architecture detection automatically. If you're on the npm path, make sure you're running an ARM-native Node.js (not an x86 version through Rosetta), as this can cause subtle performance issues.
# Verify you're running ARM Node.js
node -p "process.arch"
# Should output: arm64
How Do I Fix "claude: command not found"?
If the install succeeded but the command isn't found, the binary's directory isn't in your PATH.
First, find where npm installed it.
npm root -g
The claude binary lives in the bin/ folder one level up from that path.
# Example: if npm root is /usr/local/lib/node_modules, check /usr/local/bin
ls $(npm prefix -g)/bin/claude
If the file exists, add its directory to PATH.
echo "export PATH=\"$(npm prefix -g)/bin:\$PATH\"" >> ~/.bashrc
source ~/.bashrc
If you've customized npm's prefix (as recommended in the installation fix above), use that path instead.
npm config get prefix
# Example output: /home/username/.npm-global
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
Open a new shell session or run source ~/.bashrc after making the change. This fixes the issue in the vast majority of cases.
How Do You Diagnose Slow Performance?
When Claude Code responses become abnormally slow, the cause usually falls into one of three categories.
1. Context Window Bloat
Long sessions fill up the context window, which degrades response quality and speed. Check current token usage with /cost.
If usage exceeds 80%, compress with /compact or start fresh with /clear. For strategies to manage context proactively, see How I Reduced Claude Code Token Consumption by 50% and Context Window Exceeded Fix.
2. MCP Server Overhead
Too many MCP servers add latency to every tool call. Disable unused servers through the Claude Code UI — press @ to see connected servers and toggle them off.
You can also check MCP server status with claude doctor, which reports any servers that are failing or slow to respond.
3. Network or API-Side Issues
Anthropic API response times vary with server load. Check the status page first. Then run claude doctor to verify API connectivity from your machine.
claude doctor
What Should I Do When Nothing Else Works?
If none of the above resolved the issue, gather logs and escalate.
Collect Debug Information
# Run with verbose logging (shows tool calls and API interactions)
claude --verbose 2>&1 | tee claude-verbose.log
# For deeper protocol-level tracing (MCP debugging)
claude --debug --mcp-debug 2>&1 | tee claude-debug.log
# Collect environment info
node --version
npm --version
claude --version
uname -a
echo $SHELL
echo $PATH
claude auth status
Report to GitHub Issues
Claude Code bugs are tracked in the official repository. Before opening a new issue:
- Search existing issues — your problem may already have a solution
- Include: OS, Node.js version, error message, and debug log
- Add clear reproduction steps
GitHub Issues reach the dev team more reliably than community forums. The official troubleshooting documentation is also worth checking — it's updated frequently.
FAQ
Does Claude Code work on the free plan?
No. Claude Code requires a paid plan — Pro ($20/month), Max ($100–200/month), or Team Premium ($150/person/month). You can also use it with a direct API key from the Anthropic Console, which is billed by usage.
What Node.js version does Claude Code need?
If you use the native installer, no Node.js is required at all. For the npm installation method, you need Node.js 18 or higher — I recommend Node.js 22 LTS for the best compatibility. Use nvm to manage versions.
Should I use the native installer or npm?
Use the native installer unless you have a specific reason not to. It's Anthropic's recommended method since late 2025 — zero dependencies, auto-updates, and eliminates most installation issues. The npm method still works but requires Node.js 18+ and manual updates.
How do I check if Anthropic's API is down?
Visit the Anthropic status page. If the API is experiencing issues, local troubleshooting won't help — wait for the service to recover.
Can I use Claude Code behind a corporate proxy?
Yes. Set npm config set proxy and npm config set https-proxy for installation, and NODE_EXTRA_CA_CERTS for custom CA certificates. See the installation section for details.
Why does Claude Code keep disconnecting on WSL2?
Usually caused by WSL2's networking layer, sleep/wake cycles, or memory pressure from the vmmem process. See the dedicated guide: Fix WSL2 Claude Code Disconnects.
How do I reset Claude Code completely?
Remove credentials, clear the cache, and reinstall:
claude auth logout
npm uninstall -g @anthropic-ai/claude-code
rm -rf ~/.claude
npm install -g @anthropic-ai/claude-code
claude auth login
What's the difference between claude doctor, --verbose, and --debug?
They serve different purposes. claude doctor runs a quick health check (Node version, auth, network, MCP config). claude --verbose starts Claude Code with expanded logging that shows tool calls and API interactions — useful for understanding what's happening during a session. claude --debug enables deeper protocol-level tracing, and --mcp-debug adds MCP-specific diagnostics on top of that.
How do I use Claude Code on a remote server without a browser?
Set the API key as an environment variable instead of using browser-based login:
export ANTHROPIC_API_KEY="sk-ant-..."
Or use claude auth login and press c to copy the OAuth URL, then open it on any device with a browser.
Wrapping Up
Almost every Claude Code problem falls into one of three categories:
- Installation issues: Node.js version, npm permissions, PATH configuration, proxy settings
- Authentication issues: API key validity, subscription plan, environment variables
- Environment-specific issues: WSL/Windows conflicts, path resolution, sandbox dependencies
Get into the habit of running claude doctor first — it dramatically speeds up diagnosis. And before you spend an hour debugging, check the Anthropic status page to rule out a service outage.
Once setup is complete, the next step is writing a CLAUDE.md file to give Claude Code project-specific context. That's where the real productivity gains start. If you're running multiple projects, the multi-instance guide covers how to manage parallel sessions effectively. And if you're wondering how Claude Code stacks up against alternatives, check out the Claude Code vs Cursor and Claude Code vs GitHub Copilot comparisons.