Claude Code Won't Start: Complete Diagnostic Checklist

Claude Code startup failures typically fall into four categories. This guide provides a systematic checklist to identify and resolve the root cause.

Four Common Failure Patterns

Missing environment setup: Node.js or npm not installed
PATH or permission issues: Executable inaccessible or path not configured
Network or proxy problems: No internet connection or proxy blocking
Node.js version mismatch: Using an unsupported old version

Step 1: Verify Node.js and npm Installation

# Check if Node.js is installed
node --version
# Expected output: v18.16.0 or higher
 
# Check npm version
npm --version
# Expected output: 9.0.0 or higher

If Node.js isn't installed:

macOS (using Homebrew):

brew install node

Ubuntu/Debian:

curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

Windows: Download the LTS version from nodejs.org.

Update Node.js if Needed

Claude Code requires Node.js 16.x or newer:

# Update Node.js (Homebrew)
brew upgrade node
 
# Update npm
npm install -g npm@latest

Step 2: Verify PATH Configuration

If Node.js is installed but you get "command not found", PATH isn't configured correctly.

# Check node path
which node
# Expected: /usr/local/bin/node
 
# Check npm path
which npm
# Expected: /usr/local/bin/npm

If either command isn't found:

Add the following to your shell configuration file (.bash_profile, .zshrc, .bashrc):

# Add to ~/.bash_profile or ~/.zshrc
export PATH="/usr/local/bin:$PATH"
 
# Apply the configuration
source ~/.bash_profile  # for bash
# or
source ~/.zshrc         # for zsh

Open a new terminal window for changes to take effect.

Step 3: Install or Verify Claude Code

Claude Code is managed as an npm package.

# Check if Claude Code is installed globally
npm list -g claude-code
# or
claude-code --version

If not installed:

# Install Claude Code globally
npm install -g claude-code
 
# Verify installation
claude-code --version

If you get permission errors:

# Method 1: Using sudo (simple but not recommended)
sudo npm install -g claude-code
 
# Method 2: Fix npm permissions (recommended)
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH="$PATH:$HOME/.npm-global/bin"
 
# Add the PATH export to ~/.bash_profile or ~/.zshrc

Step 4: Verify Executable Permissions (macOS/Linux)

# Check executable permissions
ls -la $(which claude-code)
# Expected: -rwxr-xr-x (first "rwx" shows execute permission)
 
# If execute permission is missing, add it
chmod +x $(which claude-code)

Step 5: Configure Proxy (Corporate Networks)

In corporate proxy environments, npm cannot download packages.

# Check current proxy settings
npm config get proxy
npm config get https-proxy
 
# Set proxy (example: proxy.company.com:8080)
npm config set proxy http://proxy.company.com:8080
npm config set https-proxy http://proxy.company.com:8080
 
# For authenticated proxies
npm config set proxy http://username:password@proxy.company.com:8080
npm config set https-proxy http://username:password@proxy.company.com:8080

To clear proxy settings:

npm config delete proxy
npm config delete https-proxy

Step 6: Clear npm Cache

Corrupted cache can cause installation failures.

# Verify cache integrity
npm cache verify
 
# Force clear cache
npm cache clean --force
 
# Reinstall Claude Code
npm install -g claude-code

Step 7: Check Firewall Settings

Security software or firewalls may block npm downloads.

Windows Defender:

Settings → Security → Virus & threat protection → Manage settings
Add npm folder (C:\Users\[Username]\AppData\Roaming\npm) to exclusions

macOS:

System Settings → Security & Privacy
Check that npm isn't being blocked by the firewall

Common Error Messages and Solutions

"command not found: claude-code"

Solution:

Run Step 2 (PATH verification)
Rerun npm install from Step 3
Open a new terminal window

"EACCES: permission denied"

Solution: Run Step 4 (fix permissions) or Step 3 (npm permission setup).

"npm ERR! code ENOTFOUND" (Network Error)

Solution:

Check internet: ping 8.8.8.8
If behind proxy, configure in Step 5
Verify npm registry: npm config get registry (default: https://registry.npmjs.org/)

"node version is too old"

Solution: Run Step 1 to update Node.js to 18.x or newer.

Startup Verification Checklist

Confirm all of these before attempting to run Claude Code:

[ ] node --version shows 16.x or newer
[ ] npm --version shows 9.x or newer
[ ] which claude-code returns a path
[ ] claude-code --version displays the version
[ ] (macOS/Linux) Executable permissions exist (ls -la shows rwx)
[ ] Network connection is active (ping 8.8.8.8 succeeds)
[ ] (Corporate networks) npm proxy is configured

Complete Startup Test

# Open a new terminal window
# Run these commands in order
 
# 1. Verify environment
echo "=== Node and npm Versions ==="
node --version
npm --version
 
# 2. Verify Claude Code
echo "=== Claude Code Verification ==="
claude-code --version
 
# 3. Test startup
echo "=== Startup Test ==="
claude-code --help
 
# If help text appears, setup is successful

Looking back

Most Claude Code startup issues can be resolved using this checklist. Work through the steps in order to identify and fix the problem. For more detailed configuration examples, see the Complete Claude Code Setup Guide.