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
`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 `&& is not valid`	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
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
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
`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

Agents and parallel work

MCP

Skills

Plugins

Artifacts

Automation

Guides

Troubleshooting

Troubleshoot installation and login

Find your error

Run diagnostic checks

Check network connectivity

​Find your error

​Run diagnostic checks

​Check network connectivity

Find your error

Run diagnostic checks

Check network connectivity