Troubleshooting (Installation & Initial Setup)

A summary of common issues and solutions you may encounter when installing Claude Code for the first time.

---

Installation

claude: command not found

This happens when you type claude after a native installation but the command cannot be found.

# Check installation path
which claude
ls ~/.local/bin/claude   # Default installation path on Linux/macOS

# Add to PATH (bash)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Add to PATH (zsh, macOS default)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Permission error EACCES after npm installation

❌ sudo npm install -g @anthropic-ai/claude-code  ← Never do this

Installing with sudo will lead to permission issues across your entire npm setup. The correct solution:

# Use nvm (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install --lts
nvm use --lts
npm install -g @anthropic-ai/claude-code

Won't run after installation on Windows

# If winget path is not in PATH
$env:PATH += ";$env:LOCALAPPDATA\Microsoft\WinGet\Packages"

# If it's a PowerShell execution policy issue
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

---

Login

Browser doesn't open automatically

# Manually print the login URL
claude auth login --print-url
# Paste the output URL directly into your browser

"Not authenticated" error after logging in

# Check login status
claude auth status

# Log out and log back in
claude auth logout
claude auth login

Can't connect on a corporate network (VPN/proxy)

# Configure proxy settings
export HTTPS_PROXY=http://your-proxy:port
export HTTP_PROXY=http://your-proxy:port
claude

---

Running

It modified the wrong files when run from a subdirectory

Claude Code treats the directory where it's launched as the root. Always run it from the top-level project directory.

# Wrong — run from /apps/api
cd /my-project/apps/api
claude   # ← Doesn't know the full project structure

# Correct — run from the project root
cd /my-project
claude   # ← Can understand the full structure

Response stops mid-way (timeout)

# Cancel current task
ESC once

# Check context status
/context

# If too full, compress or reset
/compact   # Compress, keeping only a core summary
/clear     # Full reset

"Context window full" error

The context is full. Compress it with /compact, or use /clear and then use TODO.md to carry the context forward. → How to use TODO.md

---

Version and Updates

# Check current version
claude --version

# Update
claude update          # Native installation
npm update -g @anthropic-ai/claude-code   # npm installation

💡 The auto-memory (/memory) feature is only supported in v2.1.59 or later. Check your version first.

---

If the issue still isn't resolved

1. Check the official documentation
2. Run with the claude --debug flag to check logs
3. Check recent log files in the ~/.claude/logs/ directory