Page history
Troubleshoot installation and login
troubleshoot-install
History
troubleshoot-install Changed · +25 / -0 lines
### `Raw mode is not supported` during install
from line 15
| `curl: (22) The requested URL returned error: 403` | [Install script returned 403](#install-script-returns-html-instead-of-a-shell-script) | | `curl: (23)` or `curl: (56) Failure writing output to destination` | [Check connectivity or use an alternative installer](#curl-56-failure-writing-output-to-destination) | | `Killed` during install on Linux, or `Installation was killed before it could finish (exit code 137)` | [Free memory or add swap space](#install-killed-on-low-memory-linux-servers) | +| `Raw mode is not supported` during install | [Rerun the installer](#raw-mode-is-not-supported-during-install) | | `TLS connect error` or `SSL/TLS secure channel` | [Update CA certificates](#tls-or-ssl-connection-errors) | | `Failed to fetch version` or can't reach download server | [Check network and proxy settings](#check-network-connectivity) | | `irm is not recognized` or `&& is not valid` | [Use the right command for your shell](#wrong-install-command-on-windows) |
from line 634
``` 2. **Give Docker more memory** if using Docker Desktop. Build containers share the memory allocated to the Docker Desktop virtual machine, so open **Settings > Resources** in Docker Desktop, raise the memory limit, and rerun the build. + +### `Raw mode is not supported` during install + +When your organization's [server-managed settings](/docs/en/server-managed-settings) include changes that need [security approval](/docs/en/server-managed-settings#security-approval-dialogs), Claude Code versions before 2.1.246 try to show the approval dialog during `claude install`. The dialog needs a terminal on stdin. When the installer runs `claude install` from a pipe, as `curl -fsSL https://claude.ai/install.sh | bash` does, stdin is the pipe rather than a terminal, so the install fails with an error containing `Raw mode is not supported`. + +Claude Code v2.1.246 and later don't show the dialog during `claude install` or `claude update`. The command runs with the settings you last approved, and Claude Code shows the dialog in your next interactive session. If your organization's startup configuration [waits for the settings fetch](/docs/en/server-managed-settings#enforce-fail-closed-startup), such as when it sets `forceRemoteSettingsRefresh`, the dialog still appears during these commands, and an install run from a pipe still fails. + +In every other configuration, rerunning the installer gets past this error, because the script runs the latest release's `install` command even when you ask it to install an older version. Rerun the command for your platform: + +<Tabs> + <Tab title="macOS/Linux"> + ```bash theme={null} + curl -fsSL https://claude.ai/install.sh | bash + ``` + </Tab> + + <Tab title="Windows PowerShell"> + ```powershell theme={null} + irm https://claude.ai/install.ps1 | iex + ``` + </Tab> +</Tabs> + +`claude --version` prints the version the rerun installed. ### `claude update` or `claude doctor` hangs
troubleshoot-install Changed · +1 / -38 lines
from line 501
### `Failed to fetch version from downloads.claude.ai` -The installer couldn't reach the download server. This typically means `downloads.claude.ai` is blocked on your network. +The installer couldn't reach the download server. This typically means `downloads.claude.ai` is blocked on your network. See [Check network connectivity](#check-network-connectivity). -**Solutions:** - -1. **Test connectivity directly**: - - ```bash theme={null} - curl -sI https://downloads.claude.ai/claude-code-releases/latest - ``` - - An `HTTP/2 200` line means the server is reachable. 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](https://www.anthropic.com/supported-countries) - * `5xx`: usually a temporary service issue; wait a few minutes and retry - -2. **If behind a proxy**, set `HTTPS_PROXY` so the installer can route through it. See [proxy configuration](/docs/en/network-config#proxy-configuration) for details. - ```bash theme={null} - export HTTPS_PROXY=http://proxy.example.com:8080 - curl -fsSL https://claude.ai/install.sh | bash - ``` - -3. **If on a restricted network**, try a different network or VPN, or use an alternative install method: - - On macOS: - - ```bash theme={null} - brew install --cask claude-code - ``` - - On Windows: - - ```powershell theme={null} - winget install Anthropic.ClaudeCode - ``` - - Then run `claude --version` to confirm: the command prints a version number such as `2.1.211 (Claude Code)`. If the shell reports `claude` isn't found, open a new terminal window and retry: the session you installed from keeps its old `PATH`. - ### Wrong install command on Windows If you see `'irm' is not recognized`, `The token '&&' is not valid`, `A parameter cannot be found that matches parameter name 'fsSL'`, or `'bash' is not recognized as the name of a cmdlet`, you copied the install command for a different shell or operating system. If the command prints the script's text instead of installing anything, you ran only part of it.
from line 594
Installation was killed before it could finish (exit code 137). This usually means the system ran out of memory. Claude Code needs roughly 512MB of free memory to install. Free up memory, then run this script again. ``` - -Before v2.1.200, the script exited with only the shell's bare `Killed` line and no explanation. Installing needs roughly 512 MB of free memory, and running Claude Code needs more. See the [system requirements](/docs/en/setup#system-requirements).
troubleshoot-install First recorded · 1053 lines, first recorded
# 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 ### `command not found: claude` after installation ### `curl: (56) Failure writing output to destination` ### Homebrew cask unavailable or outdated ### TLS or SSL connection errors ### `Failed to fetch version from downloads.claude.ai` ### Wrong install command on Windows ### `The process cannot access the file` during Windows install ### Install killed on low-memory Linux servers ### Install hangs in Docker ### `claude update` or `claude doctor` hangs ### Claude Desktop overrides the `claude` command on Windows ### Claude Code on Windows requires either Git for Windows (for bash) or PowerShell ### Claude Code does not support 32-bit Windows ### Linux musl or glibc binary mismatch ### `Illegal instruction` ### `dyld: cannot load` on macOS ### `Exec format error` on WSL1 ### npm install errors in WSL ### Permission errors during installation ### Native binary not found after npm install ## Login and authentication ### Reset your login ### OAuth error: Invalid code ### 403 Forbidden after login ### This organization has been disabled with an active subscription ### OAuth login fails in WSL2, SSH, or containers ### Not logged in or token expired ### Bedrock, Agent Platform, or Foundry credentials not loading ## Still stuck
The first capture of this source. The page was already there, and this is what it said.
# 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](/docs/en/troubleshooting). For configuration problems such as settings not applying or hooks not firing, see [Debug your configuration](/docs/en/debug-your-config).
## 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](#command-not-found-claude-after-installation) |
| `syntax error near unexpected token '<'` | [Install script returns HTML](#install-script-returns-html-instead-of-a-shell-script) |
| `curl: (22) The requested URL returned error: 403` | [Install script returned 403](#install-script-returns-html-instead-of-a-shell-script) |
| `curl: (23)` or `curl: (56) Failure writing output to destination` | [Check connectivity or use an alternative installer](#curl-56-failure-writing-output-to-destination) |
| `Killed` during install on Linux, or `Installation was killed before it could finish (exit code 137)` | [Free memory or add swap space](#install-killed-on-low-memory-linux-servers) |
| `TLS connect error` or `SSL/TLS secure channel` | [Update CA certificates](#tls-or-ssl-connection-errors) |
| `Failed to fetch version` or can't reach download server | [Check network and proxy settings](#check-network-connectivity) |
| `irm is not recognized` or `&& is not valid` | [Use the right command for your shell](#wrong-install-command-on-windows) |
| `Cask 'claude-code' is unavailable: No Cask with this name exists` | [Update Homebrew](#homebrew-cask-unavailable-or-outdated) |
| `'bash' is not recognized as the name of a cmdlet` | [Use the Windows installer command](#wrong-install-command-on-windows) |
| `A parameter cannot be found that matches parameter name 'fsSL'` | [Use the Windows installer command](#wrong-install-command-on-windows) |
| `Claude Code on Windows requires either Git for Windows (for bash) or PowerShell` | [Install a shell](#claude-code-on-windows-requires-either-git-for-windows-for-bash-or-powershell) |
| `Claude Code does not support 32-bit Windows` | [Open Windows PowerShell, not the x86 entry](#claude-code-does-not-support-32-bit-windows) |
| `The process cannot access the file ... because it is being used by another process` | [Clear the downloads folder and retry](#the-process-cannot-access-the-file-during-windows-install) |
| `Error loading shared library` | [Wrong binary variant for your system](#linux-musl-or-glibc-binary-mismatch) |
| `Illegal instruction` | [Architecture or CPU instruction set mismatch](#illegal-instruction) |
| `cannot execute binary file: Exec format error` in WSL | [WSL1 native-binary regression](#exec-format-error-on-wsl1) |
| PowerShell installer completes but `claude` is not found or shows an old version | [Add the install directory to your PATH](#verify-your-path), then open a new terminal |
| `dyld: Symbol not found`, `dyld: cannot load`, or `Abort trap` on macOS | [Binary incompatibility](#dyld-cannot-load-on-macos) |
| `claude update` hangs after `Checking for updates`, or `claude doctor` hangs with no output | [Move the directory at a shell config path](#claude-update-or-claude-doctor-hangs) |
| `Invoke-Expression` or `iex` parse errors quoting HTML tags or CSS, or `ParserError` with `ParseException` | [Install script returns HTML](#install-script-returns-html-instead-of-a-shell-script) |
| `running scripts is disabled on this system` or `PSSecurityException` | [Allow the npm shims to run](#running-scripts-is-disabled-on-this-system) |
| `Error: claude native binary not installed` | [Complete the npm install](#native-binary-not-found-after-npm-install) |
| `npm error code ENOTEMPTY` during update or reinstall | [Remove the leftover package directory](#npm-enotempty-during-update-or-reinstall) |
| On Windows, the install command prints script text and nothing installs | [Run the complete install command](#wrong-install-command-on-windows) |
| `App unavailable in region` | Claude Code is not available in your country. See [supported countries](https://www.anthropic.com/supported-countries). |
| `unable to get local issuer certificate` | [Configure corporate CA certificates](#tls-or-ssl-connection-errors) |
| `OAuth error` or `403 Forbidden` | [Fix authentication](#login-and-authentication) |
| `Unable to connect to Anthropic services` during setup | See [Unable to connect to Anthropic services](/docs/en/errors#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](#bedrock-agent-platform-or-foundry-credentials-not-loading) |
| `ChainedTokenCredential authentication failed` or `CredentialUnavailableError` | [Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry credentials](#bedrock-agent-platform-or-foundry-credentials-not-loading) |
| `API Error: 500`, `529 Overloaded`, `429`, or other 4xx and 5xx errors not listed above | See the [Error reference](/docs/en/errors) |
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](/docs/en/desktop-quickstart) lets you install and use Claude Code through a graphical interface. Download it for [macOS](https://claude.ai/api/desktop/darwin/universal/dmg/latest/redirect?utm_source=claude_code\&utm_medium=docs) or [Windows](https://claude.com/download?utm_source=claude_code\&utm_medium=docs) and start coding without any command-line setup. On Linux, install the app with apt by following the [Linux install instructions](/docs/en/desktop-linux).
</Tip>
## Run diagnostic checks
### Check network connectivity
The installer downloads from `downloads.claude.ai`. Verify you can reach it:
<Tabs>
<Tab title="macOS/Linux">
```bash theme={null}
curl -sI https://downloads.claude.ai/claude-code-releases/latest
```
</Tab>
<Tab title="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.
</Tab>
</Tabs>
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](https://www.anthropic.com/supported-countries)
* `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:
<Tabs>
<Tab title="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>
<Tab title="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
```
</Tab>
</Tabs>
### 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.
<Note>
The [VS Code extension](/docs/en/vs-code) 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](/docs/en/setup) to use `claude` from a terminal, then continue below.
</Note>
Check if the install directory is in your PATH by listing your PATH entries and filtering for `local/bin`:
<Tabs>
<Tab title="macOS/Linux">
```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, the default on most Linux distributions:
```bash theme={null}
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
```
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
```
</Tab>
<Tab title="Windows PowerShell">
```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
```
</Tab>
<Tab title="Windows CMD">
```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
```
</Tab>
</Tabs>
### Check for conflicting installations
Multiple Claude Code installations can cause version mismatches or unexpected behavior. Check what's installed:
<Tabs>
<Tab title="macOS/Linux">
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
```
</Tab>
<Tab title="Windows PowerShell">
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"
```
</Tab>
</Tabs>
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
The installer needs write access to `~/.local/bin/` and `~/.claude/` on macOS and Linux. On Windows the install location is under `%USERPROFILE%`, which is writable by your user by default, so this section rarely applies there.
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>
Cut at 300 lines.