npm install succeeded, but claude returns "command not found." I wasted a full hour on the first day I tried to start a project with Claude Code.
"I followed the instructions exactly — why isn't this working?" That kind of situation usually comes from a pile-up of environment-specific issues. In this guide, I've catalogued every common failure pattern with causes and fixes, organized by OS. Use this as your go-to reference whenever setup grinds to a halt.
What Should I Do First When Claude Code Won't Start?
If Claude Code is at least partially running, there's one thing to do first.
claude doctor
This command automatically checks:
- Node.js version compatibility
- Authentication token validity
- Network connectivity
- Configuration file integrity
Any ✗ in the output points directly to the root cause. Search the error message verbatim, or jump to the relevant section below.
If claude itself won't start, doctor isn't available — treat it as an installation problem and move to the next section.
How Do I Fix Claude Code Installation Failures?
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 is a quick workaround, but it tends to create other permission headaches down the line. The cleaner fix 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 on anything below 18, switching with nvm is the most reliable approach.
nvm install 20
nvm use 20
nvm alias default 20
Pattern 3: npm install Hanging
This is common in proxy environments or on 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
Why Am I Getting 401 or 403 Authentication Errors in Claude Code?
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: A plan restriction or insufficient API key permissions. Claude Code is only available on certain subscription tiers — verify your account status.
To reset authentication:
# Remove existing credentials
claude logout
# Re-authenticate
claude login
In headless environments where a browser can't open (remote servers, for example), 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 logging into Claude Code from a different device on the same account. If it fails there too, the issue is on the account side and you'll need to contact Anthropic support.
What Causes Claude Code to Fail in WSL?
If you're using WSL (Windows Subsystem for Linux) on Windows, there are a few unique problems to watch out for.
Windows npm Bleeding into WSL
Run which npm inside WSL. If the path starts with /mnt/c/..., you're calling the Windows-side npm. You need to install Node.js separately inside WSL.
# Install nvm inside WSL
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc
nvm install 20
nvm use 20
Browser Authentication Not Opening
claude login tries to open a browser, but in WSL environments the default browser often doesn't launch. The most reliable workaround is to set the API key directly via environment variable (see the authentication section above).
File Path Issues
When working with files on the Windows side from within WSL, use the /mnt/c/... path format. That said, I strongly recommend keeping your Claude Code working directories inside WSL itself (under ~/). Mounting Windows-side filesystems tends to cause both performance and compatibility problems.
Does Switching to Windows Native Fix WSL Issues with Claude Code?
If WSL issues refuse to budge, consider moving to a native Windows environment. Claude Code runs natively on Windows too.
# Run in PowerShell
npm install -g @anthropic-ai/claude-code
A few caveats for the native Windows approach:
- Path separators are
\, which can break shell scripts - Git for Windows is required
- Some Unix commands aren't available
For most development work, WSL is actually the better environment once it's properly set up. Try resolving WSL-specific issues first using the steps above, and only fall back to native Windows if you're truly stuck.
How Do I Fix "claude: command not found"?
If the install succeeded but the command isn't found, the binary's directory simply 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 /usr/local/bin/claude
If the file exists, add its directory to PATH.
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
If you've customized npm's prefix, add that bin directory 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.
What Should I Do When Nothing Else Works?
If none of the above resolved the issue, it's time to gather logs and escalate.
Get Debug Logs
claude --debug 2>&1 | tee claude-debug.log
Collect Environment Info
node --version
npm --version
claude --version # if it starts
uname -a # OS info
echo $SHELL
echo $PATH
Reporting to GitHub Issues
Claude Code bugs are tracked in the official repository.
- Search existing issues at github.com/anthropics/claude-code/issues
- If your issue isn't there, open a new one
- Include: OS, Node.js version, error message, and debug log
GitHub Issues reach the dev team more reliably than community forums. Clear reproduction steps tend to get faster responses.
Wrapping Up
Almost every Claude Code problem falls into one of three categories:
- Installation issues: Node.js version, npm permissions, PATH configuration
- Authentication issues: API key validity, subscription plan, environment variables
- Environment-specific issues: WSL/Windows conflicts, path resolution
Get into the habit of running claude doctor first — it dramatically speeds up the diagnosis process. When you're still stuck after that, searching the error message directly in GitHub Issues usually turns up a solution that someone else already found.
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.