Claude Code Installation Failed? Find Your Exact Error

Jump to: quick triage · permission denied (EACCES) · killed / out of memory · hangs in Docker · download fails · script returns HTML · command not found · npm-specific errors · Windows claude.exe missing · things worth clarifying · FAQ

Start Here: What Does Your Error Say?

Error 1 - "EACCES: Permission Denied" During Install

What you see: the native installer fails with EACCES: permission denied naming a path, or an npm install fails with an EACCES error.

Why it happens

Anthropic's own support documentation says this "usually means the install was run with sudo, or your global npm directory is root-owned." The native installer writes to several locations under your home directory - ~/.claude/downloads/, ~/.local/bin/, ~/.local/share/claude/, ~/.local/state/claude/, and ~/.cache/claude/ (or the XDG_DATA_HOME / XDG_STATE_HOME / XDG_CACHE_HOME equivalents, if you've set them) - and the error names whichever one it couldn't write to.

How to fix it

1. Check whether the directories are writable:

   test -w ~/.local/bin && echo "writable" || echo "not writable"
   test -w ~/.claude && echo "writable" || echo "not writable"

2. If either prints "not writable," create the directory and take ownership of it:

   sudo mkdir -p ~/.local/bin
   sudo chown -R $(whoami) ~/.local

3. If you got the EACCES error from an npm install specifically, don't rerun it with sudo - switch to the native installer instead:

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

   Alternatively, point npm's global prefix at a directory you own: npm config set prefix ~/.npm-global, then add that directory's bin folder to your PATH.

What you should see: the installer completes, and claude --version prints a version number.

Error 2 - Install "Killed" (Out of Memory) on Linux

What you see: on Linux, the install prints Killed, or the newer, clearer message: "Installation was killed before it could finish (exit code 137). This usually means the system ran out of memory. Claude Code needs roughly 512MB of free memory to install."

Why it happens

Exit code 137 means the process received SIGKILL - on a low-memory host, that's almost always the Linux kernel's out-of-memory (OOM) killer stepping in. This is common on small VPS and cloud instances, since installing needs roughly 512MB of free memory and running Claude Code afterward needs more (Anthropic's system requirements list at least 4GB of RAM to run it). Before Claude Code v2.1.200, the install script only printed the shell's bare Killed line, without the explanation.

How to fix it

1. Add swap space so the install can use disk as overflow memory:

   sudo fallocate -l 2G /swapfile
   sudo chmod 600 /swapfile
   sudo mkswap /swapfile
   sudo swapon /swapfile

2. Close other processes on the server to free up memory before installing.
3. Retry the install: curl -fsSL https://claude.ai/install.sh | bash
4. If the server is consistently tight on memory, move to a larger instance - Claude Code needs at least 4GB of RAM to run day to day, not just to install.

What you should see: the install completes without a Killed message, and claude --version prints a version number.

Error 3 - Install Hangs or Never Finishes Inside Docker

What you see: the install step inside a Docker build hangs, runs for a very long time, or consumes far more memory than expected.

Why it happens

Anthropic's documentation names the specific cause: "installing as root into / can cause hangs" because, run from the filesystem root, the installer scans the entire filesystem, which drives memory usage up and slows things down dramatically inside a container.

How to fix it

1. Set a working directory before running the installer, so the scan is limited to a small, empty directory:

   WORKDIR /tmp
   RUN curl -fsSL https://claude.ai/install.sh | bash

2. If you're using Docker Desktop, the build shares memory with Docker Desktop's own virtual machine - open Settings > Resources, raise the memory limit, and rerun the build.

What you should see: the RUN step completes in roughly the same time as any other download-and-install layer.

Error 4 - "Failed to Fetch Version" or the Download Fails Partway

What you see: Failed to fetch version from downloads.claude.ai, curl: (56) Failure writing output to destination (or the related curl: (23)), a TLS error such as unable to get local issuer certificate or SELF_SIGNED_CERT_IN_CHAIN, or a message that the connection dropped or timed out mid-download.

Why it happens

The installer, and claude update afterward, download from downloads.claude.ai. Anthropic's documentation points to a few distinct causes: a corporate firewall or proxy blocking that host; a regional network restriction; outdated CA certificates, or a corporate proxy doing TLS inspection with its own certificate, which produces the TLS errors above. For an update specifically, Claude Code retries a dropped connection or a failed checksum up to three times (a completed HTTP error, like a 404, isn't retried, since the server already answered); a download that stays connected but doesn't finish within 10 minutes fails instead with Download timed out: exceeded the total deadline and isn't retried automatically. Before v2.1.202, a single dropped connection failed the download immediately with the bare error aborted instead of retrying.

How to fix it

1. Test whether you can reach the download host at all:

   curl -sI https://downloads.claude.ai/claude-code-releases/latest

   A 200 status means you reached the server (any earlier failure was likely temporary - just retry). A 403 usually means a proxy or network filter is blocking the host, or that Claude Code isn't available in your region. No output, or Could not resolve host, points to the network blocking the connection outright.
2. If you're behind a corporate proxy, set it before installing or updating:

   export HTTPS_PROXY=http://proxy.example.com:8080
   export HTTP_PROXY=http://proxy.example.com:8080
   curl -fsSL https://claude.ai/install.sh | bash

   Ask your IT team for the proxy address if you don't already have it.
3. For a TLS error from a corporate proxy's own certificate, trust that certificate for the install (curl --cacert /path/to/corporate-ca.pem -fsSL https://claude.ai/install.sh | bash), and set NODE_EXTRA_CA_CERTS to the same file so the running CLI trusts it too. On Windows, ask IT to add the proxy's certificate to the Windows certificate store instead.
4. For a dropped or timed-out update download, just run claude update again - on an otherwise healthy connection it usually succeeds on the next attempt. For a timeout specifically, try a faster or less-throttled network rather than retrying immediately on the same one.

What you should see: the curl connectivity check returns a 200, and the install or update completes.

Error 5 - Install Script Returns HTML Instead of Running

What you see: instead of installing, you get an error that quotes a web page or XML - in Bash or Zsh, syntax error near unexpected token '<' followed by '<!DOCTYPE html>'; in PowerShell, parse errors quoting HTML or CSS, or an error naming System.Xml.XmlDocument; in CMD, < was unexpected at this time. followed by HTML; or a bare curl: (22) The requested URL returned error: 403 with no page at all.

Why it happens

All of these mean the install URL returned a web page, an XML document, or an error status instead of the actual install script - usually a temporary routing or service issue, a corporate proxy or firewall blocking the request, or running the wrong installer command for your shell (PowerShell's irm piped to iex on one platform, curl piped to bash on another). If the error quotes "App unavailable in region," Claude Code isn't available in your country.

How to fix it

1. Retry the original install command after a few minutes - this is often temporary.
2. Make sure you're using the right command for your shell: curl -fsSL https://claude.ai/install.sh | bash in Bash/Zsh on macOS or Linux, irm https://claude.ai/install.ps1 | iex in PowerShell, or curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd in CMD.
3. If retrying doesn't help, use an alternative installer. On macOS: brew install --cask claude-code (run brew update first if Homebrew reports the cask doesn't exist - the local cask index can be stale, and typically runs about a week behind the latest release; use the claude-code@latest cask instead if you need the newest version). On Windows: winget install Anthropic.ClaudeCode. Note that unlike the native installer, Homebrew and WinGet installs don't update themselves automatically.
4. If you're in a supported country and still see a bare 403, work through the network checks in Error 4 first, since the alternative installers reach the same hosts.

What you should see: claude --version prints a version number such as 2.1.211 (Claude Code) once the install finishes.

Error 6 - Install Finished, But "claude: Command Not Found"

What you see: the installer reports success, but running claude gives command not found: claude on macOS, bash: claude: command not found on Linux, or 'claude' is not recognized on Windows.

Why it happens

The native installer places claude at ~/.local/bin/claude on macOS and Linux, or %USERPROFILE%\.local\bin\claude.exe on Windows, but it doesn't add that directory to your PATH itself - it only reports the problem, under "Setup notes," with a line like "Native installation exists but ~/.local/bin is not in your PATH." If you only installed the VS Code extension, this is expected: it bundles its own private copy of the CLI for its chat panel and never places a claude binary on your terminal PATH at all.

How to fix it

1. Confirm the binary is actually there: ls -la ~/.local/bin/claude on macOS/Linux, or Test-Path "$env:USERPROFILE\.local\bin\claude.exe" in PowerShell. If it's missing and you haven't installed Claude Code any other way, run the install command again.
2. If the binary is there, add its folder to your PATH. On Zsh (default on macOS): echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc. On Bash on Linux, use ~/.bashrc instead; on Bash on macOS, use ~/.bash_profile. On Windows PowerShell, add it to your User PATH permanently: $p=[Environment]::GetEnvironmentVariable('PATH','User'); [Environment]::SetEnvironmentVariable('PATH',"$p;$env:USERPROFILE\.local\bin",'User'), then open a new terminal.
3. If the echo command itself fails with permission denied, your shell config file is owned by another user or isn't writable - check with ls -l ~/.zshrc, then either sudo chown $(whoami) ~/.zshrc (if another user owns it) or chmod u+w ~/.zshrc (if you own it but it's read-only).
4. Open a brand-new terminal window and run claude --version to confirm. A window that was already open, or a terminal running inside an editor, keeps its old PATH.

What you should see: claude --version prints a version number in a fresh terminal.

Error 7 - "claude Native Binary Not Installed" or npm ENOTEMPTY

What you see: after installing or updating with npm, running claude prints Error: claude native binary not installed. with an explanation about postinstall not running; or an npm install -g over an existing install fails with npm error code ENOTEMPTY.

Why it happens

The @anthropic-ai/claude-code npm package downloads the real native binary as a separate, per-platform optional dependency during its postinstall step; until that step runs, claude is just a placeholder script. Anthropic's documentation flags a specific, common cause: npm version 12 silently skips the postinstall step unless it's explicitly allowed, via --ignore-scripts, some pnpm configurations, or --omit=optional skipping the platform-specific package outright. Running npm --version tells you if that's the cause. Separately, ENOTEMPTY happens when npm can't move the old package directory aside during an update - the npm error path line in the output names the exact directory that's blocking it, often left over from an earlier interrupted install.

How to fix it

1. For the native-binary error on npm 12: switch to the native installer and remove the npm package, so future updates don't hit this again:

   curl -fsSL https://claude.ai/install.sh | bash
   npm uninstall -g @anthropic-ai/claude-code

   If you need to stay on npm, allow Claude Code's install scripts explicitly: npm config set "allow-scripts=@anthropic-ai/claude-code" --location=user (check npm config get allow-scripts first and keep any packages already listed there).
2. For ENOTEMPTY: delete the directory named in the npm error path line, plus any leftover temp directories next to it:

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

   Then reinstall: npm install -g @anthropic-ai/claude-code.

What you should see: claude --version prints a version number instead of the native-binary error.

Error 8 - On Windows, "claude.exe" Missing After an Update

What you see: right after Claude Code updates itself on Windows, the terminal starts reporting 'claude' is not recognized again.

Why it happens

To update on Windows, Claude Code renames the existing claude.exe aside to a timestamped backup (claude.exe.old.<timestamp>) before moving the new version into place. If that move fails and Claude Code can't rename the backup back either, the install directory is left with the backup but no working claude.exe. Before v2.1.281, a related bug could delete that backup while claude.exe was still missing, removing your fallback too.

How to fix it

1. First check that %USERPROFILE%\.local\bin is actually on your PATH at all - if it isn't, this is really Error 6, not a missing file.
2. If the folder is on your PATH, rename the newest backup back to claude.exe in PowerShell:

   Get-ChildItem "$env:USERPROFILE\.local\bin\claude.exe.old.*" | Sort-Object Name | Select-Object -Last 1 | Rename-Item -NewName claude.exe

3. Confirm it worked with claude --version. If there's no claude.exe.old.* file to restore, or claude still fails, reinstall instead: irm https://claude.ai/install.ps1 | iex.

What you should see: claude --version prints a version number again.

Things Worth Clarifying

• Installing the VS Code extension is not the same as installing the CLI. The extension bundles its own private copy of Claude Code for its chat panel and never places a claude command on your terminal PATH. If you only have the extension and want to run claude from a terminal, you need the separate standalone install - that's expected behavior, not a broken extension.
• Multiple old installs can cause confusing, intermittent failures that look like a fresh install bug. A leftover npm global install, a legacy local npm install at ~/.claude/local/, or an old Homebrew or WinGet package can conflict with a newer native install. Anthropic recommends keeping only the native install and removing the others (npm uninstall -g @anthropic-ai/claude-code, rm -rf ~/.claude/local, brew uninstall --cask claude-code, or winget uninstall Anthropic.ClaudeCode, as applicable).
• "Installation failed" immediately followed by what looks like a success message isn't necessarily a real failure. It can point to a stale lock file or a leftover install from a previous attempt rather than a fresh problem - run claude --version first to check whether it actually works before troubleshooting further.
• An update failure isn't the same category of problem as an install failure, even though the fixes often overlap. A red "Auto-update failed · Run claude doctor" line in the session footer just means a background update didn't apply; your current install keeps working, and running claude update yourself (not from inside a session) either completes it or shows you the same error categories covered above.
• "AddPackage failed," including with HRESULT 0x80073CFF or 0x80073CF6, isn't a Claude Code CLI error at all. It's a Windows MSIX installer failure from the separate Claude Desktop app, not from the native installer, npm, Homebrew, or WinGet installs this guide covers. It's an open, unresolved issue with no official fix as of this writing - reported workarounds (Group Policy trust settings, Developer Mode, importing the signer certificate, reinstalling as administrator) haven't resolved it for everyone. If you hit this, you're installing Claude Desktop, not the Claude Code CLI; the fixes on this page won't apply.

When It Isn't a Bug

• Needing roughly 512MB of free memory just to install, and 4GB to run Claude Code day to day, is a stated system requirement - a small VPS failing on memory isn't a Claude Code defect, it's an undersized box for the job.
• The installer refusing to run as root at the filesystem root in Docker, or scanning slowly when it does, is a known tradeoff of that setup, not a hang that needs a bug report - setting WORKDIR to a small directory avoids it entirely.
• A spend-cap-style block isn't part of installation - if you get past installing and logging in but then hit a usage or billing wall, that's a separate topic; see the rate-limit guide instead.

What to Include When You Ask for Help

• the exact error text or exit code, copied word for word, including anything printed under "Setup notes";
• your operating system and, on Linux, whether you're on glibc or musl (ldd --version 2>&1 | head -1) and whether you're inside WSL or Docker;
• which install method you used (native installer, npm, Homebrew, or WinGet), and whether you have more than one installed (which -a claude on macOS/Linux, where.exe claude on Windows);
• the output of claude doctor, run from a normal shell rather than from inside a Claude Code session.

Related

For errors that show up after Claude Code is installed and working, see the Claude Code troubleshooting guide. If you can run claude but can't log in, see the login and OAuth error guide. For an overview of what Claude Code covers as a platform, see the Claude Code platform page.

Frequently Asked Questions

Sources

Checked on November 2, 2026:

• Claude Code docs: Troubleshoot installation and login
• Claude support: Troubleshoot Claude Code installation and authentication