# Claude Code Installation and login troubleshooting

> Claude Code: Installation, PATH, conflicting installations, permissions, TLS/proxies, Windows/WSL, Docker, login, and OAuth.

URL: https://docs.passion8.cc/en/docs/claude-code/install-troubleshooting
Language: en
Publisher: Passion8

This page covers problems before the CLI runs normally. If it starts but settings, hooks, MCP, or memory fail, see [Configuration debugging](https://docs.passion8.cc/en/docs/claude-code/configuration-debugging). For runtime API failures, see [Error reference](https://docs.passion8.cc/en/docs/claude-code/error-reference).

## Run diagnostics first

```bash
claude doctor
claude --version
which -a claude
```

Windows PowerShell:

```powershell
claude doctor
claude --version
where.exe claude
```




Native installations usually live at ~/.local/bin/claude or %USERPROFILE%\.local\bin\claude.exe. The CLI bundled with the VS Code extension is not the same as a terminal claude command.




## Quick reference

| Symptom | First action |
| --- | --- |
| command not found: claude | Add the installation directory to PATH |
| Windows not recognized | Open a new terminal; inspect the user .local/bin directory |
| Installer returns HTML | Proxy, login page, or firewall replaced the download |
| curl: (56) | Network interruption or unwritable output directory |
| TLS/SSL failure | Check corporate CA, proxy, and certificate chain |
| Homebrew cask missing | Update Homebrew or use the native installer |
| Linux installer Killed | Insufficient memory; add swap or use another machine |
| Docker installation hangs | Use noninteractive installation, a pinned version, and dependencies |
| Windows shell syntax error | Do not mix PowerShell, CMD, and Bash syntax |
| WSL npm installation fails | Use Linux Node/npm inside WSL, not Windows paths |
| OAuth invalid code | Retry with the browser and CLI in the intended environment |
| 403 after login | Account, organization, region, or enterprise policy |

## Network and downloads

Check access to the official download domain:

```bash
/usr/bin/curl -sI https://downloads.claude.ai/claude-code-releases/latest
```

In PowerShell, use curl.exe rather than the curl alias:

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

For a corporate proxy:

```bash
export HTTP_PROXY="http://proxy.example.com:8080"
export HTTPS_PROXY="http://proxy.example.com:8080"
```

For TLS errors, first trust the corporate root certificate in the system. If Node needs an extra CA:

```bash
export NODE_EXTRA_CA_CERTS="/path/to/corporate-ca.pem"
```

## PATH

macOS/Linux:

```bash
echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin"
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
claude --version
```

Bash users should replace .zshrc with .bashrc.

Windows PowerShell:

```powershell
$env:PATH -split ';' | Select-String '\.local\\bin'
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')
```

Open a new terminal after changing PATH.

## Conflicting installations

Multiple claude binaries can produce inconsistent versions or invoke an older installation.

macOS/Linux:

```bash
which -a claude
ls -la ~/.local/bin/claude
ls -la ~/.claude/local/
npm -g ls @anthropic-ai/claude-code 2>/dev/null
```

Remove an obsolete npm global installation only after confirming it is the unwanted one:

```bash
npm uninstall -g @anthropic-ai/claude-code
rm -rf ~/.claude/local
```

If you previously used Homebrew and intend to remove that installation:

```bash
brew uninstall --cask claude-code
```

Windows PowerShell:

```powershell
where.exe claude
Test-Path "$env:USERPROFILE\.local\bin\claude.exe"
Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\local"
```

The removal commands affect the old local installation directory, not all Claude configuration. Inspect paths before running them.

## Permissions and directories

| Symptom | Action |
| --- | --- |
| Cannot write ~/.local/bin | Check ownership |
| Global npm permission error | Prefer native installation over sudo npm install -g |
| curl output write failure | Check disk, directory permissions, and temporary directory |
| macOS quarantine or dyld failure | Reinstall the official binary for the correct architecture |
| Linux musl/glibc mismatch | Use the binary for the distribution |
| Illegal instruction | CPU/architecture incompatible with the binary |
| WSL1 Exec format error | Upgrade to WSL2 or use a compatible installation |

## Windows and WSL

| Environment | Recommendation |
| --- | --- |
| PowerShell | Use the PowerShell installer, not the Bash installer |
| CMD | Reopen after PATH changes |
| Git Bash | Confirm Bash exists; avoid mixing Windows and WSL paths |
| WSL2 | Install Linux Node and Claude Code inside WSL |
| 32-bit Windows | Unsupported; use a normal 64-bit environment |
| Docker | Preinstall dependencies and CAs; avoid interactive login requirements |

Claude Code needs a supported shell. If your version requests Git for Windows or PowerShell, install the required shell and retry.

## Login and OAuth

For official-account authentication problems:

```bash
claude /login
claude doctor
```

If login state is confused, inspect claude doctor before resetting it. Platform-specific state differs; do not blindly delete all of ~/.claude.

| Symptom | Possible cause |
| --- | --- |
| OAuth invalid code | Redirect intercepted, stale code, browser/CLI mismatch |
| 403 after login | Region, disabled organization, plan, or enterprise policy |
| WSL/SSH/container login failure | Browser callback cannot reach the remote shell; use the appropriate API-key flow or local login |
| Token expired | Repeat /login for the official account |
| Missing cloud credentials | Check provider environment, profile, and permissions |

## Passion8 authentication

Passion8 normally requires no official OAuth login. Configure the gateway credentials:

```bash
ANTHROPIC_BASE_URL="https://passion8.cc" \
ANTHROPIC_AUTH_TOKEN="sk-YOUR_PASSION8_API_KEY" \
claude -p "Reply only with ok"
```

If this works but interactive mode fails, shell/user/project settings may not pass the variables to that process. Continue with [Configuration debugging](https://docs.passion8.cc/en/docs/claude-code/configuration-debugging).

## Official references

- [Troubleshoot installation and login](https://code.claude.com/en/docs/en/troubleshoot-install.md)
- [Setup Claude Code](https://code.claude.com/en/docs/en/setup.md)
- [Debug your configuration](https://code.claude.com/en/docs/en/debug-your-config.md)
- [Error reference](https://code.claude.com/en/docs/en/errors.md)