Installation and login troubleshooting
Installation, PATH, conflicting installations, permissions, TLS/proxies, Windows/WSL, Docker, login, and OAuth.
This page covers problems before the CLI runs normally. If it starts but settings, hooks, MCP, or memory fail, see Configuration debugging. For runtime API failures, see Error reference.
#Run diagnostics first
claude doctor
claude --version
which -a claudeWindows PowerShell:
claude doctor
claude --version
where.exe claudeNative 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:
/usr/bin/curl -sI https://downloads.claude.ai/claude-code-releases/latestIn PowerShell, use curl.exe rather than the curl alias:
curl.exe -sI https://downloads.claude.ai/claude-code-releases/latestFor a corporate proxy:
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:
export NODE_EXTRA_CA_CERTS="/path/to/corporate-ca.pem"#PATH
macOS/Linux:
echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin"
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
claude --versionBash users should replace .zshrc with .bashrc.
Windows 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:
which -a claude
ls -la ~/.local/bin/claude
ls -la ~/.claude/local/
npm -g ls @anthropic-ai/claude-code 2>/dev/nullRemove an obsolete npm global installation only after confirming it is the unwanted one:
npm uninstall -g @anthropic-ai/claude-code
rm -rf ~/.claude/localIf you previously used Homebrew and intend to remove that installation:
brew uninstall --cask claude-codeWindows 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:
claude /login
claude doctorIf 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:
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.
#Official references
Support
Need help?
For setup, billing, or model issues, email us. Check the status page for uptime.
WeChat / QQ support is available at the bottom right.
