Fix "Failed to run Claude Code: Error: Could not..." and Install Errors

Failed to run Claude Code: Error: Could not ... is not one error — it is a wrapper reporting someone else's error, and the fix depends entirely on the words after Error:.

The Failed to run Claude Code: prefix is added by whatever tried to launch the CLI: an IDE extension, a desktop app, an MCP server, a CI job, or a script that shells out to claude. Claude Code itself never prints that prefix. The wrapper caught a failure while starting the binary and pasted the underlying message onto the end. Read the text after Error: and match it below.

Find Your "Could Not" Error

If your message ends in something not listed here, the first diagnostic is always the same:

claude doctor

Run it from a normal terminal, not from inside the tool that failed. It checks the install, the PATH and the authentication state in one pass, and it tells you which of the causes below applies.

Error: claude native binary not installed

This is the most common cause when the wrapper was launched from a project that installed Claude Code through npm. The @anthropic-ai/claude-code package downloads the real binary as a per-platform optional dependency, and a postinstall script copies it into place. Until that script runs, claude is only a placeholder shell script.

The message names its own fix:

node node_modules/@anthropic-ai/claude-code/install.cjs

That works only if the platform package was downloaded but the postinstall was skipped. If optional dependencies were skipped instead, nothing was downloaded and you must reinstall. Error: claude native binary not installed shows how to tell the two apart in one command, and covers the incomplete corporate npm mirror case.

Could not find native binary package

If postinstall cannot run in your environment at all, the package ships a wrapper that finds the downloaded platform package and launches it, at the cost of an extra Node process on every start:

node node_modules/@anthropic-ai/claude-code/cli-wrapper.cjs

If that wrapper prints Could not find native binary package, the platform package was never downloaded in the first place. Fix the optional-dependencies cause above and reinstall — the wrapper cannot conjure a binary that is not on disk.

Could not locate the Claude CLI on PATH

This wording comes from the IDE extensions rather than the CLI. The extension spawns claude as a subprocess, and that subprocess inherits the PATH of the editor process - which is usually not the PATH your login shell builds. Launching an editor from the Dock, Start menu or Spotlight is the common trigger.

The same extension failure also surfaces as Claude CLI not found. Please install Claude Code CLI. from third-party wrappers. Both are covered, with the VS Code detection regression and the fixes for each launch method, in Could not locate the Claude CLI on PATH.

spawn claude ENOENT and spawn node ENOENT

ENOENT from a spawn call means the named executable was not found on the PATH of the process doing the spawning. The distinction matters:

• spawn claude ENOENT — the claude binary is missing or not on PATH. Verify with ls -la ~/.local/bin/claude, then fix your PATH using the section below.
• spawn node ENOENT — Node itself is not on PATH. This hits GUI applications and background agents that never source your shell profile, and it is especially common with nvm, which defines node inside ~/.nvm and only exports it for interactive shells.

# Where is node, really?
command -v node

# nvm users: check whether node exists outside an interactive shell
env -i "$HOME/.nvm/versions/node/$(node -v)/bin/node" -v

The durable fix for both is the native installer, which has no Node dependency at all.

Could not resolve host

A DNS or network failure during download or at runtime. Your network is blocking the connection — corporate proxies, split-horizon DNS and captive portals are the usual causes. Test the endpoint directly, then configure your proxy environment variables (HTTP_PROXY, HTTPS_PROXY) before retrying.

Related download failures worth knowing: curl: (23) Failure writing output to destination and curl exit code 56 both mean the install script was not received in full, so Bash executed a truncated file. Download to disk first and inspect it before running:

curl -fsSL https://claude.ai/install.sh -o install.sh
head -5 install.sh   # should be a shell script, not HTML
sh install.sh

If head shows HTML, a proxy or captive portal returned a login page instead of the script — which is also the cause of syntax error near unexpected token '<'.

Could not load credentials

If you configured Claude Code to use a cloud provider, you will see Could not load credentials from any providers on Amazon Bedrock, Could not load the default credentials on Google Cloud's Agent Platform, or ChainedTokenCredential authentication failed on Microsoft Foundry. In every case the provider's own CLI is not authenticated in the shell Claude Code is running in. Authenticate with that provider's CLI first, in the same shell, and re-run.

Quick Fix: The Recommended Installation Method

Before troubleshooting, ensure you're using the official installer:

macOS and Linux:

curl -fsSL https://claude.ai/install.sh | sh

Windows (via WSL - Recommended):

# In WSL terminal
curl -fsSL https://claude.ai/install.sh | sh

Windows (Native PowerShell - Experimental):

irm https://claude.ai/install.ps1 | iex

After installation, restart your terminal and run:

claude --version

"command not found: claude"

This is the most common issue after installation. For a step-by-step walkthrough of just this error, including how to tell it apart from a permission failure, see zsh: command not found: claude. If your editor reports the CLI missing while the terminal finds it fine, see Could not locate the Claude CLI on PATH instead.

The three causes are a PATH that the current terminal has not picked up yet, a PATH entry that was never written to your shell profile, and a PATH entry written to the profile of a shell you no longer use. The dedicated guide walks through distinguishing and fixing all three.

Permission Denied Errors

During Installation

Error: Permission denied: /usr/local/bin/claude

Fix: The installer should install to ~/.local/bin (user directory), not /usr/local/bin (system directory). If you see this:

1. Don't use sudo - it creates permission problems later
2. Re-run the installer without sudo:

curl -fsSL https://claude.ai/install.sh | sh

When Running Claude

Error: Permission denied: ~/.local/bin/claude

Fix:

# Make the binary executable
chmod +x ~/.local/bin/claude

# Verify
ls -la ~/.local/bin/claude
# Should show: -rwxr-xr-x

npm Installation Issues

If you installed via npm (not recommended but still works):

"npm: command not found"

Install Node.js first:

macOS:

brew install node

Linux (Ubuntu/Debian):

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

npm Permission Errors

Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules'

Fix: Configure npm to use a user directory:

# Create npm global directory
mkdir ~/.npm-global

# Configure npm to use it
npm config set prefix '~/.npm-global'

# Add to PATH
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

# Now install Claude
npm install -g @anthropic-ai/claude-code

npm ENOTEMPTY When Updating

Reinstalling over an existing global install can fail while npm moves the old directory aside:

npm error code ENOTEMPTY
npm error syscall rename
npm error path /home/you/.nvm/versions/node/v22.13.1/lib/node_modules/@anthropic-ai/claude-code
npm error dest /home/you/.nvm/versions/node/v22.13.1/lib/node_modules/@anthropic-ai/.claude-code-tVWAnUUt
npm error errno -39
npm error ENOTEMPTY: directory not empty, rename '...'

The npm error path line names the directory npm could not move. Delete it along with any leftover .claude-code-* directories beside it, which interrupted runs leave behind, then reinstall:

npm root -g
rm -rf "$(npm root -g)/@anthropic-ai/claude-code" "$(npm root -g)/@anthropic-ai/.claude-code-"*
npm install -g @anthropic-ai/claude-code

If the directory named in the error is not under the path npm root -g prints — which happens after switching Node versions with nvm — delete the directory the error names instead.

Migrating from npm to Official Installer

If you previously installed via npm and want to switch:

# Remove npm version
npm uninstall -g @anthropic-ai/claude-code

# Install official version
curl -fsSL https://claude.ai/install.sh | sh

# Verify
claude --version

Your configuration in ~/.claude/ is preserved during migration.

macOS-Specific Issues

Xcode Command Line Tools Required

Error: xcode-select: error: command line tools are not installed

Fix:

xcode-select --install

Wait for the installation to complete, then retry the Claude installation.

A macOS upgrade can also leave the tools installed but the active developer directory pointing at a path that no longer exists. That variant reports xcrun: error: invalid active developer path instead, and needs the directory repointed rather than a plain reinstall.

Apple Silicon (M1/M2/M3) Issues

Claude Code runs natively on Apple Silicon. If you encounter issues:

1. Ensure you're not running under Rosetta:

uname -m
# Should show: arm64 (not x86_64)

2. If using Homebrew, ensure it's the ARM version:

which brew
# Should show: /opt/homebrew/bin/brew (not /usr/local/bin/brew)

Gatekeeper Blocking Installation

Error: "claude" cannot be opened because it is from an unidentified developer

Fix:

# Remove quarantine attribute
xattr -d com.apple.quarantine ~/.local/bin/claude

Windows-Specific Issues

Best Practice: Use WSL

Windows Subsystem for Linux provides the most reliable experience:

1. Install WSL:

wsl --install

2. Restart your computer

3. Open Ubuntu (or your chosen distro) and install Claude:

curl -fsSL https://claude.ai/install.sh | sh

Two WSL faults derail this before Claude Code is even involved. If wsl --install or the distro launch ends in WSL "Catastrophic failure", the E_UNEXPECTED error is coming from WSL's own components and must be cleared first. If the distro opens but the curl line hangs or fails with Temporary failure in name resolution, DNS inside WSL is broken — the installer is fine, it simply cannot resolve the host.

PowerShell Execution Policy

Error: running scripts is disabled on this system

Fix:

# Run as Administrator
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

If that command is rejected, or the block returns on the next launch, a Group Policy is setting the policy above your user scope — running scripts is disabled on this system covers the scope precedence and the per-file unblock that works when you cannot change the machine policy.

Antivirus Interference

Windows Defender or other antivirus software may block the installation:

1. Temporarily disable real-time protection
2. Run the installer
3. Re-enable protection
4. Add Claude's directory to exclusions if issues persist

Native Windows Path Issues

If using native Windows (not WSL), PATH may not update:

1. Search for "Environment Variables" in Windows
2. Edit "Path" under User variables
3. Add: %USERPROFILE%\.local\bin
4. Restart PowerShell

Linux-Specific Issues

Missing Dependencies

Error: error while loading shared libraries

Fix (Ubuntu/Debian):

sudo apt-get update
sudo apt-get install -y libssl-dev ca-certificates

Fix (Fedora/RHEL):

sudo dnf install -y openssl-devel ca-certificates

curl Not Installed

Error: curl: command not found

Fix:

# Ubuntu/Debian
sudo apt-get install -y curl

# Fedora/RHEL
sudo dnf install -y curl

# Then run the installer
curl -fsSL https://claude.ai/install.sh | sh

Verifying Your Installation

After installation, verify everything works:

# Check version
claude --version

# Check installation path
which claude

# Run diagnostics
claude doctor

# Test authentication
claude auth status

A healthy install prints a version number, resolves which claude to the binary you expect (a single path, not several), reports no problems from claude doctor, and shows your account from claude auth status. If which claude resolves somewhere you did not install to, you have a second copy shadowing the first — remove it before troubleshooting anything else.

Authentication After Installation

Once installed, authenticate with your Anthropic account:

claude

This opens a browser for authentication. After logging in, you'll see:

Successfully authenticated as: your-email@example.com

Authentication Troubleshooting

Can't open browser automatically:

Copy the URL printed in the terminal and open it manually in any browser, then paste the resulting code back. On WSL, point the CLI at the Windows browser first:

export BROWSER="explorer.exe"
claude auth login

Authentication fails:

1. Ensure you have a Claude.ai account with Claude Code access
2. Check your subscription includes Claude Code (Pro plan or higher)
3. Try logging out of claude.ai in your browser first

Uninstalling and Reinstalling

If all else fails, try a clean reinstall:

# Remove Claude CLI
rm -rf ~/.local/bin/claude
rm -rf ~/.claude

# Clear npm cache (if used npm)
npm cache clean --force

# Reinstall
curl -fsSL https://claude.ai/install.sh | sh

Getting Help

If you're still having issues:

1. Check the official docs: Claude Code Documentation
2. Search GitHub issues: Claude Code Issues
3. Run diagnostics: claude doctor provides detailed system information

Next Steps

• Where Configuration Files Are Stored
• How to Fix Freezing Issues
• How to Fix Permission Errors
• How to Use Plan Mode

Same errors in other AI coding CLIs

The "command not found" PATH fix is nearly identical across tools. See the equivalent install troubleshooting for OpenAI Codex CLI, Google Gemini CLI, and GitHub Copilot CLI.