Installation & Startup

Unable to connect to Anthropic services on first launch

Symptom: After installing Claude Code, the first claude run prints this error and exits:

Unable to connect to Anthropic services
Failed to connect to api.anthropic.com: ERR_BAD_REQUEST
Please check your internet connection and network settings.

Fix: Open ~/.claude.json (Windows: C:\Users\<name>\.claude.json) in a text editor and add to the top-level JSON object:

"hasCompletedOnboarding": true

Full example:

{
  "installMethod": "unknown",
  "autoUpdates": true,
  "firstStartTime": "2025-07-14T06:11:03.877Z",
  "userID": "...",
  "projects": { },
  "hasCompletedOnboarding": true
}

Note: the } ending the projects field must be followed by a comma ,, or the JSON is invalid. Validate with:

cat ~/.claude.json | python3 -m json.tool

No error means the format is valid. Run claude again to enter the interactive UI.

command not found: claude

The npm global bin directory isn't in PATH. Run npm config get prefix, then add the corresponding /bin directory to your system PATH.

permission denied / EACCES error (Mac / Linux install)

Do not use sudo. Move npm's global directory to your user space:

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc   # zsh users: ~/.zshrc
source ~/.bashrc

permission denied error (Windows install)

Run PowerShell as administrator:

npm config set prefix "$env:APPDATA\npm"
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

How to clean up an old npm-installed Claude Code?

The official recommendation is now the native install script, not npm. Back up ~/.claude first, then remove the old package:

# Mac / Linux
if [ -d ~/.claude ]; then cp -r ~/.claude ~/.claude.backup; fi
npm list -g --depth=0
npm uninstall -g @anthropic-ai/claude-code

# Windows PowerShell
if (Test-Path "$env:USERPROFILE\.claude") { Copy-Item "$env:USERPROFILE\.claude" "$env:USERPROFILE\.claude.backup" -Recurse }
npm list -g --depth=0
npm uninstall -g @anthropic-ai/claude-code

Then reinstall with the native script:

# Mac / Linux / WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

# Windows CMD
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Or use a package manager: macOS brew install --cask claude-code, Windows winget install Anthropic.ClaudeCode.