🔥 Fix Claude Code Errors

Cause

The Claude Code binary is not in your system PATH after installation.

Fix Steps

1. Add ~/.local/bin to your PATH:
2. echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
3. source ~/.zshrc
4. Verify: claude --version

Cause

npm global install requires write access to system directories. Never use sudo.

Fix Steps

1. Use the native installer instead of npm:
2. curl -fsSL https://claude.ai/install.sh | bash
3. Or fix npm permissions: npm config set prefix ~/.npm-global

Cause

OAuth token expired or you haven't authenticated yet.

Fix Steps

1. Re-authenticate:
2. claude login
3. Follow the browser prompt to complete OAuth.
4. If using API key: export ANTHROPIC_API_KEY=your-key

Cause

You've hit the usage limit for your current plan.

Fix Steps

1. Wait a few minutes and retry.
2. Check your usage: /cost in Claude Code.
3. Use /compact to reduce token consumption.
4. Upgrade plan at claude.ai/pricing for higher limits.

Cause

Network issue — firewall, proxy, or DNS blocking the connection.

Fix Steps

1. Check internet: curl -I https://api.anthropic.com
2. If behind proxy: export HTTPS_PROXY=http://proxy:port
3. Check firewall allows HTTPS to api.anthropic.com.
4. Try: claude doctor

Cause

npm installation requires Node.js 18 or later. Native install does NOT need Node.

Fix Steps

1. Best fix — use the native installer (no Node needed):
2. curl -fsSL https://claude.ai/install.sh | bash
3. Or upgrade Node: nvm install 22 && nvm use 22

Cause

Claude Code on Windows needs WSL or Git Bash.

Fix Steps

1. Install WSL: wsl --install
2. Restart computer after WSL install.
3. Open WSL terminal and install Claude Code:
4. curl -fsSL https://claude.ai/install.sh | bash

Cause

The API request took too long. Could be network or server load.

Fix Steps

1. Retry the command.
2. Check Anthropic status: status.anthropic.com
3. If on slow network, increase timeout or use stable channel.
4. Run claude doctor to diagnose.

Cause

Alpine Linux / musl-based systems need additional dependencies.

Fix Steps

1. Install required packages:
2. apk add libgcc libstdc++ ripgrep
3. Set environment variable:
4. export USE_BUILTIN_RIPGREP=0
5. Then install Claude Code normally.

Cause

Disk is full. Claude Code needs space for the binary and cache.

Fix Steps

1. Check disk usage: df -h
2. Clear npm cache: npm cache clean --force
3. Remove old versions: rm -rf ~/.local/share/claude
4. Reinstall Claude Code.

Cause

Corporate proxy or VPN intercepting HTTPS traffic.

Fix Steps

1. If behind corporate proxy, set NODE_EXTRA_CA_CERTS:
2. export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem
3. Or try: export NODE_TLS_REJECT_UNAUTHORIZED=0 (temporary, insecure)
4. Contact IT for the corporate CA certificate.