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
Native installation exists but ... is not in your PATH Add the install directory to your PATH
INFO: Could not find files for the given pattern(s). from where.exe claude Check whether Claude Code is installed
zsh: permission denied: /Users/you/.zshrc or bash: /home/you/.bashrc: Permission denied Make your shell config file writable
syntax error near unexpected token '<' Install script returns HTML
< was unexpected at this time in CMD Install script returns HTML
The term 'System.Xml.XmlDocument' is not recognized 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 Free memory or add swap space
Installation was killed before it could finish Free memory, then rerun the installer
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
CRYPT_E_NO_REVOCATION_CHECK or CRYPT_E_REVOCATION_OFFLINE Work around blocked revocation checks
Failed to fetch version or can't reach download server Check network and proxy settings
The connection dropped while downloading the update or Download timed out: exceeded the total deadline Run the update again or set your proxy
Release verification failed for Claude Code Run claude update or claude install again
Auto-update failed · Run claude doctor in red in the session footer Run claude update from your shell
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
Cask 'claude-code@latest' is not installed Upgrade the cask you installed
'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.

[!TIP]

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:

[tab] macOS/Linux

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

[tab] Windows PowerShell

```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:

[tab] macOS/Linux

```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

[tab] Windows PowerShell

```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 installer detects this case and reports it under Setup notes: in its output: Native installation exists but ~/.local/bin is not in your PATH. on macOS and Linux, or Native installation exists but C:\Users\you\.local\bin is not in your PATH. on Windows. It prints the fix with that note but doesn't change PATH itself.

[!NOTE]

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.

First check that the program is there at all, then check whether its folder is in your PATH. The PATH fix is permanent, so you apply it once. Pick your platform's tab and run its commands there: in your terminal on macOS and Linux, or in PowerShell or Command Prompt on Windows.

[tab] macOS/Linux

Check that the installer put the program in place:

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

* **`No such file or directory`**: there's no native install. If you haven't installed Claude Code another way, such as with npm, Homebrew, or a Linux package manager, [install Claude Code](https://code.claude.com/docs/en/setup.md#install-claude-code). If you installed it another way, see [Check for conflicting installations](#check-for-conflicting-installations).
* **A listing for the file**: the program is there. Check your PATH next.

List your PATH entries and filter for the install folder:

```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. If there's no output, add it to your shell configuration with the two commands for your shell. The echo command saves the setting for every new terminal, and source applies it to the window you're in. The echo command prints nothing when it succeeds.

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.

If the `echo` command prints `permission denied`, see [`permission denied` when adding to your PATH](#permission-denied-when-adding-to-your-path).

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

If claude is still not found, check these causes:

  • The terminal predates the change: a window that was already open keeps its old PATH, and a terminal inside an editor takes its PATH from the editor. Open a new window, or quit and reopen the editor.
  • The line wasn't saved: run grep -n '.local/bin' ~/.zshrc, using your shell's file name. It prints the line with its line number when the line is there. If it prints nothing, run the two PATH commands again.
  • The line went to another shell's file: run echo $0 to see your shell, then run the two PATH commands for that shell.

[tab] Windows PowerShell

Check that the installer put the program in place:

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

* **`False`**: there's no native install. If you haven't installed Claude Code another way, such as with npm or WinGet, [install Claude Code](https://code.claude.com/docs/en/setup.md#install-claude-code). If you installed it another way, see [Check for conflicting installations](#check-for-conflicting-installations).
* **`True`**: the program is there. Check your PATH next.

List your PATH entries and filter for the install folder:

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

If this prints C:\Users\you\.local\bin, the directory is in your PATH and you can skip to Check for conflicting installations. If there's no output, add the install directory to your User PATH:

```powershell theme={null} $currentPath = Environment::GetEnvironmentVariable('PATH', 'User')

Restart your terminal for the change to take effect.

Verify the fix worked:

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

If claude is still not found in a new terminal, check these causes:

  • The terminal runs inside an editor: it takes its PATH from the editor, so quit and reopen the editor.
  • The change wasn't saved: run [Environment]::GetEnvironmentVariable('PATH', 'User') and look for .local\bin in the PATH it prints. If it's missing, run the two commands again.

[tab] Windows CMD

Check that the installer put the program in place:

```batch theme={null} dir "%USERPROFILE%.local\bin\claude.exe"

* **`File Not Found` or `The system cannot find the path specified.`**: there's no native install. If you haven't installed Claude Code another way, such as with npm or WinGet, [install Claude Code](https://code.claude.com/docs/en/setup.md#install-claude-code). If you installed it another way, see [Check for conflicting installations](#check-for-conflicting-installations).
* **A listing for `claude.exe`**: the program is there. Check your PATH next.

List your PATH entries and filter for the install folder:

```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

If claude is still not found in a new terminal, a terminal inside an editor takes its PATH from the editor, so quit and reopen the editor too.

Check for conflicting installations

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

[tab] macOS/Linux

List all claude binaries found in your PATH:

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

If this prints `claude not found`, a `no claude in` line, or nothing, no `claude` is on your PATH. The next checks show whether one is installed at all.

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.

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

If ls -la ~/.local/bin/claude printed No such file or directory, there's no native install. If you haven't installed Claude Code another way, such as with npm, Homebrew, or a Linux package manager, install Claude Code. If ~/.local/bin/claude exists but which -a claude didn't list it, the folder isn't in your PATH: see Verify your PATH.

[tab] Windows PowerShell

List all claude binaries found in your PATH:

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

If this prints `INFO: Could not find files for the given pattern(s).`, no `claude` is on your PATH.

Check whether the native installer placed a binary:

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

  • True: the native install is there. If where.exe found nothing, its folder isn't in your PATH: see Verify your PATH.
  • False: there's no native install. If you haven't installed Claude Code another way, such as with npm or WinGet, install Claude Code.

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:

> [tab] macOS/Linux
>
> ```bash theme={null}
> rm -rf ~/.claude/local
> ```

> [tab] Windows PowerShell
>
> ```powershell theme={null}
> Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\local"
> ```

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`](https://code.claude.com/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`](https://code.claude.com/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:

> [tab] macOS/Linux
>
> ```bash theme={null}
> ls -la "$(command -v claude)"
> ```

> [tab] Windows PowerShell
>
> ```powershell theme={null}
> Get-Command claude | Select-Object Source
> ```

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](https://code.claude.com/docs/en/setup.md#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

The install command fails with one of these errors when what it downloaded isn't the install script.

**Bash or Zsh**: the error quotes the first line of the returned page.

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

PowerShell, parse errors: the errors point 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"/>