Troubleshoot installation and login

If the installer fails, claude won't run, or you can't sign in, find your message in the table below and jump to the fix. Once Claude Code is running and the trouble is performance or behaviour, use Troubleshooting; for settings and hooks that don't apply, use Debug your configuration.

Tip: If you'd rather avoid the terminal altogether, the desktop app installs and runs Claude Code through a normal GUI on macOS and Windows, and through apt on Linux.

Match your error

Not listed? Work through the diagnostic checks next.

Diagnostic checks

Check network connectivity

The installer downloads from downloads.claude.ai. Ask for just the headers to see whether you can reach it:

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

On Windows PowerShell, call curl.exe explicitly. Plain curl there is an alias for Invoke-WebRequest, which rejects -sI.

Behind a corporate proxy, set both proxy variables before running the installer. Your IT team or your browser's proxy settings will have the address:

export HTTP_PROXY=http://gateway.corp.internal:3128
export HTTPS_PROXY=http://gateway.corp.internal:3128
curl -fsSL https://claude.ai/install.sh | bash

In PowerShell, set $env:HTTP_PROXY and $env:HTTPS_PROXY the same way, then run irm https://claude.ai/install.ps1 | iex.

Verify your PATH

The native installer puts the binary at ~/.local/bin/claude on macOS and Linux, and %USERPROFILE%\.local\bin\claude.exe on Windows. If the install succeeded but your shell can't find claude, that directory isn't on your PATH.

Note: The VS Code extension bundles its own private copy of the CLI and doesn't put anything on your PATH. If you've only installed the extension, ~/.local/bin/claude won't exist. Do the standalone install first.

macOS and Linux. Check whether the directory is listed:

echo "$PATH" | tr ':' '\n' | grep -Fx "$HOME/.local/bin"

No output means it's missing. Add it to the startup file your shell actually reads:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
claude --version

Windows PowerShell. Check, then add the directory to your user PATH if needed:

$env:PATH -split ';' | Select-String '\.local\\bin'

$userPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$userPath;$env:USERPROFILE\.local\bin", 'User')

Open a new terminal and run claude --version.

Windows CMD. echo %PATH% | findstr /i "local\bin" shows whether it's there. If not, add %USERPROFILE%\.local\bin to your user PATH in the Environment Variables dialog, then open a new terminal.

Check for conflicting installations

More than one install leads to version mismatches and confusing behaviour. On macOS and Linux, which -a claude lists every claude on your PATH (empty output means none, so go back to the PATH check). There are three places a copy can come from:

A No such file or directory from ls just means nothing is installed there. On Windows, where.exe claude lists copies on PATH and Test-Path "$env:USERPROFILE\.local\bin\claude.exe" checks for the native install.

Keep one, ideally the native install, and remove the rest:

Check directory permissions

A permissions failure names the path it couldn't write. On Windows everything goes under %USERPROFILE%, so this rarely bites there. On macOS and Linux the install touches:

XDG_DATA_HOME, XDG_STATE_HOME and XDG_CACHE_HOME replace the three ~/.local/share, ~/.local/state and ~/.cache locations when set, and CLAUDE_CONFIG_DIR moves the global config file. To test and fix:

for d in ~/.local/bin ~/.claude; do test -w "$d" && echo "$d ok" || echo "$d NOT writable"; done
sudo mkdir -p ~/.local/bin
sudo chown -R "$(whoami)" ~/.local

Verify the binary runs

If claude --version works but claude crashes or hangs at startup:

• Confirm the file exists and is executable: ls -la "$(command -v claude)" (PowerShell: Get-Command claude | Select-Object Source).
• On Linux, look for missing shared libraries: ldd "$(command -v claude)" | grep "not found". On Alpine and other musl systems, see Setup.

Common installation problems

The installer returned a web page

You'll see syntax error near unexpected token '<' followed by <!DOCTYPE html> from Bash, or in PowerShell a parse error from iex that quotes HTML tags or CSS (sometimes worded Missing expression after unary operator '--' or a ParserError). Saving the script with -OutFile doesn't help, because the file is the same web page. A bare curl: (22) ... 403 is the same family.

All of these mean the install URL answered with an HTML page or an error status instead of the script. If the page says "App unavailable in region", Claude Code isn't available where you are. A plain 403 can also be a proxy blocking you, so run the network check before trying alternatives, which hit the same hosts. Otherwise it's usually a temporary routing problem:

• Install through a package manager instead: brew install --cask claude-code on macOS, winget install Anthropic.ClaudeCode on Windows. Then open a new terminal (the old one keeps its old PATH) and run claude --version, which prints something like 2.1.211 (Claude Code).
• Or wait a few minutes and retry the original command.

curl (23) or (56) failure writing output

The curl ... | bash pattern pipes the script straight into Bash, and these errors mean Bash didn't get all of it. Code 56 means the download was cut off; code 23 means curl couldn't write to the pipe, usually because Bash exited early. Run the network check. If it passes, the failure was intermittent and a retry normally works, or use one of the other install methods in Setup.

Homebrew cask unavailable or out of date

Error: Cask 'claude-code' is unavailable: No Cask with this name exists means your local cask index predates the cask. Run brew update, then install again. The same stale index explains an older-than-expected version. Note that claude-code follows the stable channel, which usually trails the newest release by about a week; brew install --cask claude-code@latest gets the latest channel. Setup explains the channels.

TLS and certificate errors

Messages such as curl: (35) TLS connect error, schannel: next InitializeSecurityContext failed, or PowerShell's Could not create SSL/TLS secure channel and Could not establish trust relationship mean the TLS handshake failed. In order of likelihood:

1. Out-of-date CA certificates. On Debian or Ubuntu: sudo apt-get update && sudo apt-get install ca-certificates. On macOS, curl uses the Keychain, so updating macOS updates the roots.
2. Old TLS default on Windows. Run [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 in PowerShell, then the installer.
3. A TLS-inspecting corporate proxy. This also shows up as unable to get local issuer certificate or SELF_SIGNED_CERT_IN_CHAIN. For the install itself on macOS or Linux, pass your proxy's CA: curl --cacert ~/certs/corp-root.pem -fsSL https://claude.ai/install.sh | bash. The PowerShell installer uses the Windows certificate store, so IT needs to add the CA there. For Claude Code after installation, point NODE_EXTRA_CA_CERTS at the same bundle. Testing on a direct connection confirms whether the proxy is to blame. More in Network configuration.
4. Blocked revocation checks on Windows. CRYPT_E_NO_REVOCATION_CHECK (0x80092012) and CRYPT_E_REVOCATION_OFFLINE (0x80092013) mean curl reached the server but your network blocks the revocation lookup. Add --ssl-revoke-best-effort to the curl that downloads install.cmd: curl --ssl-revoke-best-effort -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd. The script then retries its own downloads in best-effort mode automatically. Best-effort still rejects certificates known to be revoked. The PowerShell installer and winget install Anthropic.ClaudeCode avoid curl's check entirely.

Failed to fetch version from downloads.claude.ai

The installer couldn't reach the download server, which almost always means downloads.claude.ai is blocked on your network. See Check network connectivity.

Wrong install command on Windows

Each Windows shell needs its own command, and copying the wrong one produces a recognisable error:

Whichever you used, open a new terminal and check with claude --version.

Running scripts is disabled on this system

Installing or running Claude Code via npm on Windows can fail with npm.ps1 cannot be loaded because running scripts is disabled on this system and a PSSecurityException, or the same error naming claude.ps1. PowerShell's execution policy blocks the .ps1 shims npm creates. It doesn't affect irm ... | iex, which runs the text directly. Choose one:

• Allow local scripts for your account: Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser.
• Call npm.cmd and claude.cmd, which the policy doesn't cover.
• Switch to the PowerShell installer, which installs a binary rather than a script.

File in use during Windows install

Failed to download binary: The process cannot access the file ... because it is being used by another process means the installer couldn't write to %USERPROFILE%\.claude\downloads. Another install is still running, or antivirus is scanning a half-downloaded file. Close other installer windows, give the scan a moment, then:

Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\downloads"
irm https://claude.ai/install.ps1 | iex

claude.exe missing after a Windows update

To update on Windows, Claude Code renames the running claude.exe to a backup, then moves the new one into place. If the move fails and the rename can't be undone, you're left with only the backup, a file named claude.exe.old. plus a numeric timestamp, in %USERPROFILE%\.local\bin. (If that directory isn't on PATH at all, see Verify your PATH instead.) Restore the newest backup:

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

Check with claude --version. If there's no backup or it still fails, reinstall with irm https://claude.ai/install.ps1 | iex. Versions before v2.1.281 could delete the backup while claude.exe was still missing.

Install killed on a low-memory server

On small VPS instances the Linux OOM killer can terminate the claude install step. The script reports Installation was killed before it could finish (exit code 137) and explains that it needs roughly 512MB of free memory. Running Claude Code needs more: at least 4GB of RAM. Fixes:

1. Add swap so the install can borrow disk as memory, then rerun the installer:

   sudo fallocate -l 2G /swapfile && sudo chmod 600 /swapfile
   sudo mkswap /swapfile && sudo swapon /swapfile
   curl -fsSL https://claude.ai/install.sh | bash
   

   Copy

2. Stop other processes before installing.

3. Move to a bigger instance.

Install hangs in Docker

Installing as root from / makes the installer scan the whole filesystem, which eats memory and can hang. Set a working directory first:

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

On Docker Desktop, also raise the VM memory limit under Settings > Resources, since build containers share it.

Raw mode is not supported during install

Older versions (before 2.1.246) tried to show your organisation's server-managed settings approval dialog during claude install. When the installer runs from a pipe, as curl ... | bash does, stdin isn't a terminal and the dialog fails with Raw mode is not supported. From v2.1.246, claude install and claude update use the settings you last approved and show the dialog at your next interactive session. The exception is an organisation that makes startup wait for the settings fetch (for example with forceRemoteSettingsRefresh), where the dialog still appears and a piped install still fails.

In every other case, simply rerun the installer. The script always runs the latest release's install command, even if you asked for an older version, so the rerun gets past the error.

claude update or claude doctor hangs

Both commands scan ~/.zshrc (or $ZDOTDIR/.zshrc), ~/.bashrc, ~/.config/fish/config.fish and, on macOS, the first existing of ~/.bash_profile, ~/.bash_login and ~/.profile, looking for an outdated claude alias. Before v2.1.214, a directory sitting at one of those paths made both commands hang (claude update stopped after Checking for updates, claude doctor printed nothing, and the System diagnostics section of /status stayed blank). Find the culprit with:

ls -ld ~/.zshrc ~/.bashrc ~/.bash_profile ~/.bash_login ~/.profile ~/.config/fish/config.fish 2>&1

A line starting with d is a directory. Move it aside, or update by rerunning the install script (since claude update itself hangs on affected versions).

Claude Desktop hijacks the claude command on Windows

Older Claude Desktop builds registered a Claude.exe under WindowsApps that wins on PATH, so typing claude opens the app. Update Claude Desktop.

No shell found on Windows

Git for Windows is optional: without Git Bash, Claude Code uses its PowerShell tool. The error Claude Code on Windows requires either Git for Windows (for bash) or PowerShell means it found neither.

• PowerShell missing from PATH: add C:\Windows\System32\WindowsPowerShell\v1.0\, or install PowerShell 7 (pwsh).
• Want Bash: install Git for Windows, choose "Add to PATH", and restart the terminal.
• Git installed but not detected: without CLAUDE_CODE_GIT_BASH_PATH, Claude Code checks C:\Program Files\Git and C:\Program Files (x86)\Git, then the git on your PATH (using its bin\bash.exe). It deliberately skips a git inside the folder you launched from, or below it under node_modules or a virtual-environment folder such as .venv or env, so a project can't plant one. Point the variable at your install explicitly:

{
  "env": {
    "CLAUDE_CODE_GIT_BASH_PATH": "D:\\Tools\\Git\\bin\\bash.exe"
  }
}

The variable is only honoured when the file is named bash.exe, sh.exe, bash or sh. Any other name (such as git-bash.exe), or a path that doesn't exist, is ignored with a warning visible under --debug, and Claude Code auto-detects instead. If the name is right and it still isn't used, endpoint security (AppLocker, Group Policy software restrictions, EDR) may be interfering; ask IT to allowlist claude.exe and the cmd.exe and bash.exe processes it starts.

32-bit Windows error

The Start menu has both Windows PowerShell and Windows PowerShell (x86). The x86 one is 32-bit and triggers Claude Code does not support 32-bit Windows even on 64-bit machines. Run [Environment]::Is64BitOperatingSystem in the same window. True means open the non-x86 PowerShell and try again; False means the OS itself is 32-bit, which Claude Code doesn't support.

musl or glibc mismatch on Linux

Error loading shared library libstdc++.so.6 (or libgcc_s.so.1) usually means the installer picked the wrong binary variant, which can happen on glibc systems with musl cross-compilation packages installed. Run ldd --version 2>&1 | head -1: GLIBC or GNU libc means glibc, musl means musl.

• glibc but got musl: remove the install and reinstall. You can also fetch the right binary via https://downloads.claude.ai/claude-code-releases/{VERSION}/manifest.json, and please file a GitHub issue with the output of ldd --version and ls /lib/libc.musl*.
• Genuinely musl (Alpine): apk add libgcc libstdc++ ripgrep, with ripgrep from the community repository.

Illegal instruction

The binary is using CPU instructions your processor doesn't have. Two causes:

• Wrong architecture, for example an x86 binary on ARM. Compare uname -m (or $env:PROCESSOR_ARCHITECTURE) with what you received, and file a GitHub issue if they differ.
• No AVX. Pre-2013-ish Intel and AMD CPUs, and VMs whose hypervisor hides AVX, can't run the binary. grep -m1 -ow avx /proc/cpuinfo returning nothing confirms it. There's no workaround yet; it's tracked in GitHub issue #50384, and reports should include your CPU model.

Other install methods ship the same binary, so they won't help with either.

dyld errors on macOS

dyld: Symbol not found referencing libicucore, or dyld: cannot load ... (load command 0x80000034 is unknown) followed by Abort trap: 6, both mean your macOS is too old. Claude Code needs macOS 13.0 or later. Update macOS; Homebrew installs the same binary and won't help.

Bus error during a session

If a running session dies with Bus error, possibly after a crash report mentioning panic(main thread): Bus error at address and oh no: Bun has crashed, the likely cause is that Claude Code could no longer read its own executable, for example because it was truncated or deleted on network storage. It isn't a Bun bug in that case. Start a new session. If you install onto network storage, follow the network storage guidance in Setup so upgrades don't remove binaries that running sessions still need.

Exec format error on WSL1

cannot execute binary file: Exec format error in WSL means you're on WSL1, whose loader can't handle the native binary's program headers (GitHub issue #38788). The clean fix is converting the distribution to WSL2 from PowerShell with wsl --set-version <DistroName> 2. To stay on WSL1, launch through the dynamic linker by adding this to ~/.bashrc and sourcing it:

claude() {
  /lib64/ld-linux-x86-64.so.2 "$(readlink -f "$HOME/.local/bin/claude")" "$@"
}

npm installs inside WSL

These apply only if you used npm install -g in WSL:

• Platform mismatch: WSL is probably using the Windows npm. Run npm config set os linux, then npm install -g @anthropic-ai/claude-code --force. Don't use sudo.
• exec: node: not found: which node and which npm showing /mnt/c/... paths means Windows binaries. Install Node through your distro or nvm.
• nvm conflicts: with nvm on both sides, the imported Windows PATH can win. Make sure your ~/.bashrc or ~/.zshrc loads nvm (export NVM_DIR="$HOME/.nvm" then source $NVM_DIR/nvm.sh), and if Windows paths still take priority, prepend $HOME/.nvm/versions/node/$(node -v)/bin to PATH.

Warning: Don't fix this by setting appendWindowsPath = false, which stops you calling Windows programs from WSL, or by removing Node from Windows if you use it there.

Native binary missing after npm install

The npm package delivers the real binary as a per-platform optional dependency (for example @anthropic-ai/claude-code-darwin-arm64), and a postinstall script copies it into place. If either step is skipped, claude stays a placeholder and prints Error: claude native binary not installed (on Windows, PowerShell or CMD just refuse to run the placeholder). Check:

• Optional dependencies disabled: remove --omit=optional (npm), --no-optional (pnpm) or --ignore-optional (yarn), and check .npmrc doesn't set optional=false. There's no JavaScript fallback, so the platform package must download.
• Install scripts disabled: after --ignore-scripts or some pnpm setups, run node node_modules/@anthropic-ai/claude-code/install.cjs. If postinstall can never run in your environment, node node_modules/@anthropic-ai/claude-code/cli-wrapper.cjs launches the downloaded binary at the cost of an extra Node process; if it says Could not find native binary package, fix optional dependencies first.
• Unsupported platform: binaries exist for darwin-arm64, darwin-x64, linux-x64, linux-arm64, linux-x64-musl, linux-arm64-musl, win32-x64 and win32-arm64 only. FreeBSD is reported as unsupported.
• Corporate registry mirror: it must mirror all eight @anthropic-ai/claude-code-* platform packages as well as the main package.

npm ENOTEMPTY

Reinstalling over an existing global install can fail with npm error code ENOTEMPTY while renaming the old package directory. Delete the directory the npm error path line names, plus any .claude-code-* leftovers beside it, then reinstall:

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

If you've switched Node versions with nvm, the failing path may not be under npm root -g; delete the exact directories from the error instead. In Zsh, no matches found just means there were no leftovers.

Login and authentication

Reset your login

When sign-in fails for no obvious reason, a clean re-authentication fixes most cases: run /logout, quit, start claude again and sign in. If the browser doesn't open, press c to copy the OAuth URL and paste it into a browser yourself. That also helps when the URL wraps in a narrow or SSH terminal.

OAuth error: Invalid code

OAuth error: Invalid code. Please make sure the full code was copied means the code expired or got truncated. Press Enter to retry and finish quickly once the browser opens. Over SSH the browser may open on the wrong machine, so copy the URL from the terminal into your local browser.

403 Forbidden after login

For API Error: 403 Request not allowed:

• Pro or Max: confirm the subscription is active at claude.ai/settings.
• Console users: you need the "Claude Code" or "Developer" role, which an admin assigns under Settings, then Members.
• Behind a proxy: see Network configuration.

Access not granted for this account

Authorization failed with Claude Code access has not been granted for this account. Contact your administrator. means your Claude Enterprise organisation set your role to Custom and none of the custom roles on your groups includes Claude Code. Nothing on your machine fixes this. An organisation Owner must either give one of your groups a custom role that grants Claude Code or move you to a standard role such as User. Then log in again.

"This organization has been disabled" with a working subscription

API Error: 400 ... This organization has been disabled alongside an active subscription means an old ANTHROPIC_API_KEY (often from a previous job or project) is overriding your subscription. Once approved, an environment key takes precedence over your login, and in -p mode it's always used. Unset it and remove the export from your shell profile (~/.zshrc, ~/.bashrc, ~/.profile, or $PROFILE and user environment variables on Windows):

unset ANTHROPIC_API_KEY
claude

Run /status to confirm which credential is active. Authentication explains the full precedence order.

OAuth in WSL2, SSH or containers

Here the browser usually runs on a different host and can't redirect back to Claude Code's local callback. After you sign in, the browser shows a code instead; paste it at the Paste code here if prompted prompt.

• If no browser opens from WSL2, set BROWSER to your Windows browser, for example export BROWSER="/mnt/c/Program Files/Mozilla Firefox/firefox.exe".
• Or press c to copy the URL, or use the URL that claude auth login prints, and open it locally.
• If pasting into the prompt does nothing, try your terminal's alternative paste (right-click or Shift+Insert in Windows Terminal), or run claude auth login, which reads the code from standard input. That fallback works on any terminal where interactive paste fails.

Not logged in or token expired

If you're asked to log in again, run /login. If it happens often, check your system clock, since token validation depends on accurate time. Parallel sessions on one machine share one saved login and take turns refreshing it; versions before v2.1.211 could revoke the login when two sessions refreshed with the same token after the machine woke from sleep. Error reference covers what other open sessions do after you sign in again.

macOS Keychain problems. Credentials normally go in the login Keychain. If the Keychain refuses the write (locked in an SSH session, or its password out of sync with your account), Claude Code falls back to the plaintext ~/.claude/.credentials.json, and a Console login that creates an API key fails. To move back to the Keychain:

1. Run claude doctor. A warning beginning macOS Keychain is not writable confirms the problem; no warning means skip to step 4.
2. Unlock it: security unlock-keychain ~/Library/Keychains/login.keychain-db, then run claude doctor again.
3. If that doesn't clear it, open Keychain Access, select login, and use Edit > Change Password for Keychain "login" to resync with your account password.
4. Run /logout then /login. Logging out wipes all stored credentials, including the plaintext file, saved MCP server logins and plugin secrets, so expect to re-authorise those.

Cloud provider credentials not loading

Could not load credentials from any providers (Amazon Bedrock), Could not load the default credentials (Google Cloud's Agent Platform) or ChainedTokenCredential authentication failed (Microsoft Foundry) usually means the provider CLI isn't authenticated in this shell:

If it works in your terminal but not in VS Code or JetBrains, the IDE didn't inherit your shell environment. Set the variables in the IDE's settings or launch the IDE from a terminal that has them. Full setup lives in Amazon Bedrock, Google Cloud's Agent Platform and Microsoft Foundry.

Still stuck

1. Search the GitHub issues, or open one with your OS, the install command and the full output.
2. If claude --version works, run claude doctor.
3. If you can start a session, use /feedback.
4. For account problems (login loops, an unrecognised subscription, a disabled organisation), contact Anthropic support from claude.ai or platform.claude.com: click your initials, then Get help.

Related

• Setup
• Authentication
• Network configuration
• Error reference
• Troubleshooting