Skip to content

Documentation Index

Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt Use this file to discover all available pages before exploring further.

Troubleshoot installation and login

Fix command not found, PATH, permission, network, and authentication errors when installing or signing in to Claude Code.

If installation fails or you can't sign in, find your error below. For runtime issues after Claude Code is working, see Troubleshooting. For configuration problems such as settings not applying or hooks not firing, see Debug your configuration.

Find your error

Match the error message or symptom you're seeing to a fix:

What you see Solution
command not found: claude or 'claude' is not recognized Fix your PATH
syntax error near unexpected token '<' Install script returns HTML
curl: (22) The requested URL returned error: 403 Install script returned 403
curl: (23) or curl: (56) Failure writing output to destination Check connectivity or use an alternative installer
Killed during install on Linux, or Installation was killed before it could finish (exit code 137) Free memory or add swap space
Raw mode is not supported during install Rerun the installer
EACCES: permission denied during install Fix the install directory's permissions
TLS connect error or SSL/TLS secure channel Update CA certificates
Failed to fetch version or can't reach download server Check network and proxy settings
irm is not recognized or The token '&&' is not a valid statement separator Use the right command for your shell
Cask 'claude-code' is unavailable: No Cask with this name exists Update Homebrew
'bash' is not recognized as the name of a cmdlet Use the Windows installer command
A parameter cannot be found that matches parameter name 'fsSL' Use the Windows installer command
Claude Code on Windows requires either Git for Windows (for bash) or PowerShell Install a shell
Claude Code does not support 32-bit Windows Open Windows PowerShell, not the x86 entry
The process cannot access the file ... because it is being used by another process Clear the downloads folder and retry
Error loading shared library Wrong binary variant for your system
Illegal instruction Architecture or CPU instruction set mismatch
cannot execute binary file: Exec format error in WSL WSL1 native-binary regression
Bus error or oh no: Bun has crashed while a session is running Keep the executable readable
PowerShell installer completes but claude is not found or shows an old version Add the install directory to your PATH, then open a new terminal
dyld: Symbol not found, dyld: cannot load, or Abort trap on macOS Binary incompatibility
claude update hangs after Checking for updates, or claude doctor hangs with no output Move the directory at a shell config path
Invoke-Expression or iex parse errors quoting HTML tags or CSS, or ParserError with ParseException Install script returns HTML
running scripts is disabled on this system or PSSecurityException Allow the npm shims to run
Error: claude native binary not installed Complete the npm install
npm error code ENOTEMPTY during update or reinstall Remove the leftover package directory
'claude' is not recognized right after an update on Windows Restore claude.exe from its backup
On Windows, the install command prints script text and nothing installs Run the complete install command
App unavailable in region Claude Code is not available in your country. See supported countries.
unable to get local issuer certificate Configure corporate CA certificates
OAuth error or 403 Forbidden Fix authentication
Claude Code access has not been granted for this account Get a role that includes Claude Code
Unable to connect to Anthropic services during setup See Unable to connect to Anthropic services in the Error reference
Could not load the default credentials or Could not load credentials from any providers Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry credentials
ChainedTokenCredential authentication failed or CredentialUnavailableError Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry credentials
API Error: 500, 529 Overloaded, 429, or other 4xx and 5xx errors not listed above See the Error reference

If your issue isn't listed, work through the diagnostic checks below to narrow down the cause.

If you'd rather skip the terminal entirely, the Claude Code Desktop app lets you install and use Claude Code through a graphical interface. Download it for macOS or Windows and start coding without any command-line setup. On Linux, install the app with apt by following the Linux install instructions.

Run diagnostic checks

Check network connectivity

The installer downloads from downloads.claude.ai. Verify you can reach it:

bash theme={null} curl -sI https://downloads.claude.ai/claude-code-releases/latest

powershell theme={null} curl.exe -sI https://downloads.claude.ai/claude-code-releases/latest

PowerShell aliases `curl` to `Invoke-WebRequest`, which rejects the `-sI` flags, so call `curl.exe` explicitly.

You reached the server if the first line shows a 200 status. You see HTTP/2 200 on macOS and Linux, and HTTP/1.1 200 OK from the curl.exe included with Windows. Other results point to the cause:

  • 403: usually a proxy or network filter blocking the host, or Claude Code is not available in your region
  • 5xx: usually a temporary service issue; wait a few minutes and retry

If you see no output, Could not resolve host, or a connection timeout, your network is blocking the connection. Common causes:

  • Corporate firewalls or proxies blocking downloads.claude.ai
  • Regional network restrictions: try a VPN or alternative network
  • TLS/SSL issues: update your system's CA certificates, or check if HTTPS_PROXY is configured

If you're behind a corporate proxy, set HTTPS_PROXY and HTTP_PROXY to your proxy's address before installing. Ask your IT team for the proxy URL if you don't know it, or check your browser's proxy settings.

This example sets both proxy variables, then runs the installer through your proxy:

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

powershell theme={null} $env:HTTP_PROXY = 'http://proxy.example.com:8080' $env:HTTPS_PROXY = 'http://proxy.example.com:8080' irm https://claude.ai/install.ps1 | iex

Verify your PATH

If installation succeeded but you get a command not found or not recognized error when running claude, the install directory isn't in your PATH. Your shell searches for programs in directories listed in PATH, and the installer places claude at ~/.local/bin/claude on macOS/Linux or %USERPROFILE%\.local\bin\claude.exe on Windows.

The VS Code extension does not place claude at this location. It bundles a private copy of the CLI inside the extension directory for its own chat panel and does not add it to PATH. If you have only installed the extension, ~/.local/bin/claude will not exist. Run the standalone install to use claude from a terminal, then continue below.

Check if the install directory is in your PATH by listing your PATH entries and filtering for local/bin:

```bash theme={null} echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin" 

If this prints `/Users/you/.local/bin` or `/home/you/.local/bin`, the directory is in your PATH and you can skip to [Check for conflicting installations](#check-for-conflicting-installations). If there's no output, add it to your shell configuration.

For Zsh, the default on macOS:

```bash theme={null}
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc


For Bash on Linux, where it's the default on most distributions:

```bash theme={null}
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
```

For Bash on macOS, add the line to `~/.bash_profile` instead. Terminal on macOS starts Bash as a login shell, which ignores `~/.bashrc` and reads only the first of `~/.bash_profile`, `~/.bash_login`, or `~/.profile` that exists. If you already have a `~/.bash_login` or `~/.profile` and no `~/.bash_profile`, put the line in that file rather than creating `~/.bash_profile`:

```bash theme={null}
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bash_profile
source ~/.bash_profile
```

Alternatively, close and reopen your terminal.

For other shells such as fish or Nushell, add `~/.local/bin` to your PATH using your shell's own configuration syntax, then restart your terminal.

Verify the fix worked:

```bash theme={null}
claude --version
```

```powershell theme={null} $env:PATH -split ';' | Select-String '.local\bin' 

If there's no output, add the install directory to your User PATH:

```powershell theme={null}
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')


Restart your terminal for the change to take effect.

Verify the fix worked:

```powershell theme={null}
claude --version
```

```batch theme={null} echo %PATH% | findstr /i "local\bin" 

If there's no output, open System Settings, go to Environment Variables, and add `%USERPROFILE%\.local\bin` to your User PATH variable. Restart your terminal.

Verify the fix worked:

```batch theme={null}
claude --version

Check for conflicting installations

Multiple Claude Code installations can cause version mismatches or unexpected behavior. Check what's installed:

List all claude binaries found in your PATH:

```bash theme={null}
which -a claude
```

If this prints nothing, no `claude` is on your PATH yet. Go back to [Verify your PATH](#verify-your-path).

Check the three locations a `claude` binary can come from. `~/.local/bin/claude` is the native installer, `~/.claude/local/` is a legacy local npm install created by older versions of Claude Code, and the npm global list shows a `-g` install:

```bash theme={null}
ls -la ~/.local/bin/claude
```

A native install shows a symlink into `~/.local/share/claude/versions/`. A script or a symlink you created yourself at this path is a custom launcher, which [auto-update leaves in place](/docs/en/setup#auto-updates).

If either `ls` command prints `No such file or directory`, that's not an error. It means nothing is installed at that location, so move on to the next check.

```bash theme={null}
ls -la ~/.claude/local/
```

```bash theme={null}
npm -g ls @anthropic-ai/claude-code 2>/dev/null
```

List all claude binaries found in your PATH:

```powershell theme={null}
where.exe claude
```

Check whether the native installer placed a binary:

```powershell theme={null}
Test-Path "$env:USERPROFILE\.local\bin\claude.exe"
```

If you find multiple installations, keep only one. The native install at ~/.local/bin/claude on macOS/Linux or %USERPROFILE%\.local\bin\claude.exe on Windows is recommended. Remove the extras:

Uninstall an npm global install:

```bash theme={null} npm uninstall -g @anthropic-ai/claude-code 

Remove the legacy local npm install:

<Tabs>
  <Tab title="macOS/Linux">
    ```bash theme={null}
    rm -rf ~/.claude/local
    ```
  </Tab>

  <Tab title="Windows PowerShell">
    ```powershell theme={null}
    Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\local"
    ```
  </Tab>
</Tabs>

Remove a Homebrew install on macOS. If you installed the `claude-code@latest` cask, substitute that name:

```bash theme={null}
brew uninstall --cask claude-code

Remove a WinGet install on Windows:

```powershell theme={null} winget uninstall Anthropic.ClaudeCode 

### Check directory permissions

An install that fails on permissions names the path it couldn't create or write. On Windows the install writes under `%USERPROFILE%`, which is writable by your user by default, so this section rarely applies there.

On macOS and Linux the install writes to these locations:

* `~/.claude/downloads/`: where the install command puts the downloaded binary
* `~/.local/bin/`: the `claude` launcher
* `~/.local/share/claude/`: each version it downloads
* `~/.local/state/claude/`: its lock files
* `~/.cache/claude/`: staged downloads
* [`~/.claude.json`](/docs/en/claude-directory): your global config file, where the installer records the install method

If you set `XDG_DATA_HOME`, `XDG_STATE_HOME`, or `XDG_CACHE_HOME`, the install uses those in place of `~/.local/share`, `~/.local/state`, and `~/.cache`. If you set [`CLAUDE_CONFIG_DIR`](/docs/en/env-vars), the global config file lives under that directory instead of your home directory.

Check whether the directories are writable:

```bash theme={null}
test -w ~/.local/bin && echo "writable" || echo "not writable"
test -w ~/.claude && echo "writable" || echo "not writable"

If either directory isn't writable, create the install directory and set your user as the owner:

```bash theme={null} sudo mkdir -p ~/.local/bin sudo chown -R $(whoami) ~/.local 

### Verify the binary works

If `claude --version` prints a version but `claude` crashes or hangs on startup, run these checks to narrow down the cause. If `claude --version` says command not found, go to [Verify your PATH](#verify-your-path) first; the commands below assume `claude` is on your PATH.

Confirm the binary exists and is executable:

<Tabs>
  <Tab title="macOS/Linux">
    ```bash theme={null}
    ls -la "$(command -v claude)"
    ```
  </Tab>

  <Tab title="Windows PowerShell">
    ```powershell theme={null}
    Get-Command claude | Select-Object Source
    ```
  </Tab>
</Tabs>

On Linux, check for missing shared libraries. If `ldd` shows missing libraries, you may need to install system packages. On Alpine Linux and other musl-based distributions, see [Alpine Linux setup](/docs/en/setup#alpine-linux-and-musl-based-distributions).

```bash theme={null}
ldd "$(command -v claude)" | grep "not found"

Confirm the binary can execute:

```bash theme={null} claude --version 

## Common installation issues

These are the most frequently encountered installation problems and their solutions.

### Install script returns HTML instead of a shell script

When running the install command, you may see one of these errors:

```text theme={null}
bash: line 1: syntax error near unexpected token `<'
bash: line 1: `<!DOCTYPE html>'

On PowerShell, the same problem appears as parse errors pointing into the returned page, with iex trying to run HTML and CSS as PowerShell:

```text theme={null} iex : At line:1 char:2310 + ... igin="anonymous"/>