273 lines
9 KiB
Markdown
273 lines
9 KiB
Markdown
---
|
|
title: "Claude Code Troubleshooting"
|
|
aliases: [claude-code-troubleshoot, claude-install-errors, claude-debug]
|
|
tags: [claude-code, troubleshooting, installation, auth, windows, wsl, linux, macos]
|
|
sources: [raw/Troubleshooting.md]
|
|
created: 2026-04-17
|
|
updated: 2026-04-17
|
|
---
|
|
|
|
# Claude Code Troubleshooting
|
|
|
|
Quick-reference for installation failures, auth errors, performance problems, and IDE issues.
|
|
|
|
---
|
|
|
|
## Installation Error Quick-Reference
|
|
|
|
| Symptom | Fix |
|
|
|---------|-----|
|
|
| `command not found: claude` | Add `~/.local/bin` to PATH |
|
|
| `syntax error near unexpected token '<'` | Install script returned HTML (geo-block or network issue) |
|
|
| `curl: (56) Failure writing output` | Network interrupted mid-download; retry or use Homebrew/WinGet |
|
|
| `Killed` during install on Linux | OOM — add 2 GB swap |
|
|
| `TLS connect error` / `SSL/TLS secure channel` | Update CA certs; set `NODE_EXTRA_CA_CERTS` for corporate proxy |
|
|
| `Failed to fetch version` | `storage.googleapis.com` blocked; set `HTTPS_PROXY` |
|
|
| `irm is not recognized` / `&& is not valid` | Wrong shell — use correct installer for CMD/PowerShell/Bash |
|
|
| `Claude Code on Windows requires git-bash` | Install Git for Windows; set `CLAUDE_CODE_GIT_BASH_PATH` in settings |
|
|
| `Error loading shared library` | musl/glibc mismatch — reinstall with correct binary |
|
|
| `Illegal instruction` on Linux | CPU arch mismatch (ARM vs x86) — verify with `uname -m` |
|
|
| `dyld: cannot load` / `Abort trap: 6` on macOS | macOS < 13.0 or binary incompatibility — update macOS |
|
|
| `App unavailable in region` | Country not supported |
|
|
|
|
---
|
|
|
|
## Install Diagnostics
|
|
|
|
### Network check
|
|
```bash
|
|
curl -sI https://storage.googleapis.com # installer downloads from here
|
|
```
|
|
|
|
### Proxy setup (corporate networks)
|
|
```bash
|
|
export HTTP_PROXY=http://proxy.example.com:8080
|
|
export HTTPS_PROXY=http://proxy.example.com:8080
|
|
curl -fsSL https://claude.ai/install.sh | bash
|
|
```
|
|
|
|
### PATH fix (macOS/Linux)
|
|
```bash
|
|
# Zsh
|
|
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc
|
|
|
|
# Bash
|
|
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc
|
|
```
|
|
|
|
### Conflicting installs
|
|
```bash
|
|
which -a claude # find all claude binaries
|
|
npm uninstall -g @anthropic-ai/claude-code # remove npm install
|
|
brew uninstall --cask claude-code # remove Homebrew install
|
|
```
|
|
|
|
### Directory permissions
|
|
```bash
|
|
test -w ~/.local/bin && echo "writable" || echo "not writable"
|
|
sudo mkdir -p ~/.local/bin && sudo chown -R $(whoami) ~/.local
|
|
```
|
|
|
|
---
|
|
|
|
## Platform-Specific Issues
|
|
|
|
### Linux: Low-memory install failure (`Killed`)
|
|
Claude Code requires ≥ 4 GB RAM. Add swap:
|
|
```bash
|
|
sudo fallocate -l 2G /swapfile
|
|
sudo chmod 600 /swapfile && sudo mkswap /swapfile && sudo swapon /swapfile
|
|
curl -fsSL https://claude.ai/install.sh | bash
|
|
```
|
|
|
|
### Linux: musl/glibc mismatch
|
|
```bash
|
|
ldd /bin/ls | head -1 # shows "linux-vdso" (glibc) or "musl"
|
|
# On Alpine (musl):
|
|
apk add libgcc libstdc++ ripgrep
|
|
```
|
|
|
|
### macOS: `dyld` errors
|
|
- Requires macOS 13.0+. Check: Apple menu → About This Mac
|
|
- Fallback: `brew install --cask claude-code`
|
|
|
|
### Docker: Install hangs
|
|
```dockerfile
|
|
WORKDIR /tmp
|
|
RUN curl -fsSL https://claude.ai/install.sh | bash
|
|
```
|
|
Add `--memory=4g` if using Docker Desktop.
|
|
|
|
### Windows: Shell mismatch
|
|
| Shell | Command |
|
|
|-------|---------|
|
|
| PowerShell | `irm https://claude.ai/install.ps1 \| iex` |
|
|
| CMD | `curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd` |
|
|
| WinGet | `winget install Anthropic.ClaudeCode` |
|
|
|
|
### Windows: Claude Desktop overrides CLI
|
|
Update Claude Desktop to latest — older versions register `Claude.exe` that shadows the CLI.
|
|
|
|
### Windows: Git Bash required
|
|
Install from [git-scm.com](https://git-scm.com/downloads/win). If already installed:
|
|
```json
|
|
{ "env": { "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe" } }
|
|
```
|
|
|
|
### WSL2 Issues
|
|
- **Node from Windows PATH**: `which npm` should point to `/usr/` not `/mnt/c/` — use nvm in Linux
|
|
- **OAuth login**: `export BROWSER="/mnt/c/Program Files/Google/Chrome/Application/chrome.exe"`
|
|
- **JetBrains not detected**: Add Windows Firewall rule for WSL2 subnet, or set `networkingMode=mirrored` in `.wslconfig`
|
|
- **Sandboxing**: `sudo apt-get install bubblewrap socat`; WSL1 does not support sandboxing
|
|
|
|
---
|
|
|
|
## Authentication & Permissions
|
|
|
|
### Repeated permission prompts
|
|
Use `/permissions` to allowlist specific tools.
|
|
|
|
### Auth flow reset
|
|
```
|
|
/logout → close → reopen claude → re-authenticate
|
|
```
|
|
If browser doesn't open: press `c` to copy OAuth URL.
|
|
|
|
### OAuth: Invalid code
|
|
Token expired or truncated — press Enter to retry quickly after browser opens.
|
|
|
|
### 403 Forbidden
|
|
- Claude Pro/Max: check subscription at claude.ai/settings
|
|
- Console users: verify "Claude Code" or "Developer" role assigned
|
|
- Proxy users: see [[wiki/claude-code/mcp-integration|MCP & network config]]
|
|
|
|
### Model not found
|
|
Check model setting priority (highest wins):
|
|
1. `--model` flag
|
|
2. `ANTHROPIC_MODEL` env var
|
|
3. `.claude/settings.local.json`
|
|
4. `.claude/settings.json`
|
|
5. `~/.claude/settings.json`
|
|
|
|
Run `/model` inside Claude to pick from available models.
|
|
|
|
### Disabled org with active subscription
|
|
Stale `ANTHROPIC_API_KEY` overriding subscription credentials:
|
|
```bash
|
|
unset ANTHROPIC_API_KEY
|
|
claude
|
|
# remove from ~/.zshrc or ~/.bashrc permanently
|
|
```
|
|
|
|
### macOS Keychain issues
|
|
```bash
|
|
claude doctor # check Keychain access
|
|
security unlock-keychain ~/Library/Keychains/login.keychain-db
|
|
```
|
|
|
|
### Token expired frequently
|
|
Check system clock accuracy — token validation is time-sensitive.
|
|
|
|
---
|
|
|
|
## Configuration Files
|
|
|
|
| File | Purpose |
|
|
|------|---------|
|
|
| `~/.claude/settings.json` | User settings (permissions, hooks, model overrides) |
|
|
| `.claude/settings.json` | Project settings (committed) |
|
|
| `.claude/settings.local.json` | Local project settings (not committed) |
|
|
| `~/.claude.json` | Global state (theme, OAuth, MCP servers) |
|
|
| `.mcp.json` | Project MCP servers (committed) |
|
|
|
|
### Full reset
|
|
```bash
|
|
rm ~/.claude.json && rm -rf ~/.claude/ && rm -rf .claude/ && rm .mcp.json
|
|
```
|
|
|
|
---
|
|
|
|
## Performance & Stability
|
|
|
|
### High CPU/memory
|
|
- Run `/compact` regularly
|
|
- Restart between major tasks
|
|
- Add build dirs to `.gitignore`
|
|
- Run `/heapdump` → inspect `.heapsnapshot` in Chrome DevTools
|
|
|
|
### Auto-compaction thrashing
|
|
`Autocompact is thrashing` = a single file keeps refilling context. Fix:
|
|
- Ask Claude to read file in smaller chunks (line ranges, functions)
|
|
- `/compact keep only the plan and the diff`
|
|
- Move large-file work to a [[wiki/claude-code/custom-subagents|subagent]]
|
|
- `/clear` to start fresh
|
|
|
|
### Search not working (`@file`, custom skills)
|
|
Install system ripgrep:
|
|
```bash
|
|
brew install ripgrep # macOS
|
|
winget install BurntSushi.ripgrep.MSVC # Windows
|
|
sudo apt install ripgrep # Ubuntu/Debian
|
|
apk add ripgrep # Alpine
|
|
```
|
|
Then set `USE_BUILTIN_RIPGREP=0` in environment.
|
|
|
|
### WSL: Slow / incomplete search
|
|
Move project to Linux filesystem (`/home/`) instead of `/mnt/c/`.
|
|
|
|
---
|
|
|
|
## IDE Integration
|
|
|
|
### JetBrains: Escape key not working
|
|
Settings → Tools → Terminal → uncheck "Move focus to the editor with Escape"
|
|
|
|
### JetBrains: Not detected on WSL2
|
|
Option 1 — Windows Firewall rule:
|
|
```powershell
|
|
New-NetFirewallRule -DisplayName "Allow WSL2 Internal Traffic" -Direction Inbound -Protocol TCP -Action Allow -RemoteAddress 172.21.0.0/16 -LocalAddress 172.21.0.0/16
|
|
```
|
|
Option 2 — mirrored networking in `.wslconfig`:
|
|
```ini
|
|
[wsl2]
|
|
networkingMode=mirrored
|
|
```
|
|
|
|
---
|
|
|
|
## Markdown Formatting Issues
|
|
|
|
- Code blocks missing language tags → ask: "Add appropriate language tags to all code blocks"
|
|
- Use PostToolUse hooks to auto-run `prettier` on generated markdown
|
|
- Document preferred style in `CLAUDE.md` (see [[wiki/claude-code/overview|overview]])
|
|
|
|
---
|
|
|
|
## Diagnostics Command
|
|
|
|
```
|
|
/doctor
|
|
```
|
|
Checks: install type, version, search, auto-update, settings JSON validity, MCP config errors, keybindings, context warnings, plugin loading.
|
|
|
|
---
|
|
|
|
## Key Takeaways
|
|
|
|
- **`command not found`** almost always means `~/.local/bin` is not in PATH — add it to shell config
|
|
- **Corporate networks**: set `HTTP_PROXY`/`HTTPS_PROXY` and `NODE_EXTRA_CA_CERTS` before installing
|
|
- **Linux OOM**: add swap before installing on low-RAM VPS; Claude Code needs ≥ 4 GB
|
|
- **macOS requires 13.0+**; use Homebrew as fallback install method on any platform
|
|
- **Windows**: use the right installer for your shell (PowerShell vs CMD vs WSL)
|
|
- **Auth problems**: try `/logout` → restart → re-auth; check for stale `ANTHROPIC_API_KEY` env var
|
|
- **Model not found**: check all 5 config layers in priority order; use `/model` picker to verify access
|
|
- **Performance**: `/compact` reduces context; `/heapdump` diagnoses memory growth
|
|
- **Search broken**: install system `ripgrep` and set `USE_BUILTIN_RIPGREP=0`
|
|
- **`/doctor`** is the first diagnostic to run for any unexplained issue
|
|
|
|
---
|
|
|
|
## Sources
|
|
|
|
- [Troubleshooting — Claude Code Docs](https://code.claude.com/docs/en/troubleshooting)
|
|
- See also: [[wiki/claude-code/error-reference|Error Reference]], [[wiki/claude-code/overview|Claude Code Overview]]
|