---
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]]