obsidian/wiki/claude-code/troubleshooting.md

title	aliases	tags	sources	created	updated
Claude Code Troubleshooting	claude-code-troubleshoot claude-install-errors claude-debug	claude-code troubleshooting installation auth windows wsl linux macos	raw/Troubleshooting.md	2026-04-17	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

curl -sI https://storage.googleapis.com   # installer downloads from here

Proxy setup (corporate networks)

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)

# Zsh
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc

# Bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc

Conflicting installs

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

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:

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

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

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. If already installed:

{ "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

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:

unset ANTHROPIC_API_KEY
claude
# remove from ~/.zshrc or ~/.bashrc permanently

macOS Keychain issues

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

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
• /clear to start fresh

Search not working (@file, custom skills)

Install system ripgrep:

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:

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:

[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)

---

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
• See also: wiki/claude-code/error-reference, wiki/claude-code/overview