Troubleshoot installation and login

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:

macOS/Linux
Windows PowerShell

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

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:

macOS/Linux
Windows PowerShell

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

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

macOS/Linux
Windows PowerShell
Windows CMD

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.For Zsh, the default on macOS:

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

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

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:

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:

claude --version

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

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

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

claude --version

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:

claude --version

Check for conflicting installations

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

macOS/Linux
Windows PowerShell

List all claude binaries found in your PATH:

which -a claude

If this prints nothing, no claude is on your PATH yet. Go back to 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:

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.

ls -la ~/.claude/local/

npm -g ls @anthropic-ai/claude-code 2>/dev/null

List all claude binaries found in your PATH:

where.exe claude

Check whether the native installer placed a binary:

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:

npm uninstall -g @anthropic-ai/claude-code

Remove the legacy local npm install:

macOS/Linux
Windows PowerShell

rm -rf ~/.claude/local

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:

brew uninstall --cask claude-code

Remove a WinGet install on Windows:

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: 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, the global config file lives under that directory instead of your home directory. Check whether the directories are writable:

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:

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 first; the commands below assume claude is on your PATH. Confirm the binary exists and is executable:

macOS/Linux
Windows PowerShell

ls -la "$(command -v claude)"

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.

ldd "$(command -v claude)" | grep "not found"

Confirm the binary can execute:

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:

bash: line 1: syntax error near unexpected token `<'
bash: line 1: `'

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

iex : At line:1 char:2310
+ ... igin="anonymous"/>
Assistant
Responses are generated using AI and may contain mistakes.

Agents and parallel work

MCP

Skills

Artifacts

Automation

Guides

Troubleshooting

Troubleshoot installation and login

Find your error

Run diagnostic checks

Check network connectivity

Verify your PATH

Check for conflicting installations

Check directory permissions

Verify the binary works

Common installation issues

Install script returns HTML instead of a shell script

​Find your error

​Run diagnostic checks

​Check network connectivity

​Verify your PATH

​Check for conflicting installations

​Check directory permissions

​Verify the binary works

​Common installation issues

​Install script returns HTML instead of a shell script

Find your error

Run diagnostic checks

Check network connectivity

Verify your PATH

Check for conflicting installations

Check directory permissions

Verify the binary works

Common installation issues

Install script returns HTML instead of a shell script