Claude Code Troubleshooting: Install, Auth, and Connection Issues

When Claude Code won't install or won't log in, the cause usually falls into a few set categories. This guide covers only items confirmed in Claude's official troubleshooting docs. (As of June 2026. Commands and requirements may change, so check the official docs for the latest.)

Check these basics first

• Node version: Claude Code requires Node 18 or later. Check with node -v (verify the exact minimum in the official docs at install time).
• Service status: if you suspect a widespread outage, check status.claude.com.
• Internet connection: Claude Code needs access to Anthropic's servers to work.

Installation issues

• "command not found" / claude isn't recognized: the installer added claude to your PATH, but your current shell hasn't picked it up. Open a new terminal or run source ~/.zshrc (or ~/.bashrc). On Windows, close and reopen PowerShell.
• Permission errors: usually because you installed with sudo or your global npm directory is root-owned. Do not use sudo. Use the native installer instead, or set npm's prefix to ~/.npm-global and add that bin directory to your PATH.
• Node too old: install a current LTS with nvm install --lts, or use the native installer, which bundles its own runtime and avoids the issue.
• Download blocked: a corporate network may block the download host. Set a proxy first (export HTTPS_PROXY=...) and reinstall, or ask IT for the offline package.
• Corporate certificate: if your company injects its own certificate, Node may reject it. Point Node at the corporate CA bundle with export NODE_EXTRA_CA_CERTS=/path/to/company-ca.pem and add it to your shell profile to persist.

# Check Node version (18 or later required)
node -v

# Install without sudo (avoids permission errors). Either:
curl -fsSL https://claude.ai/install.sh | bash      # native installer
npm config set prefix ~/.npm-global                 # or fix npm prefix

# Corporate network: proxy / internal certificate
export HTTPS_PROXY=http://proxy.example.com:port
export NODE_EXTRA_CA_CERTS=/path/to/company-ca.pem

# Verify the API key is visible
echo $ANTHROPIC_API_KEY

Authentication and login issues

• Browser doesn't open automatically: during login, press c to copy the OAuth URL to your clipboard, then open it in any browser to log in.
• localhost callback is blocked: common over remote SSH, in devcontainers, or behind a strict firewall. Use the manual flow instead — copy the URL printed in the terminal, log in via a browser, and paste the returned code back. In headless environments (CI/CD, Docker), set ANTHROPIC_API_KEY to bypass OAuth.
• API key not recognized: the key may have been exported in a different shell, so run echo $ANTHROPIC_API_KEY to check it's visible in the current one. Claude Code also prompts once on first use to trust the key.
• If it still fails, re-authenticate cleanly: when login fails and the cause isn't obvious, a clean re-auth resolves most cases. Restart claude and complete the authentication again.
• Only fails in the IDE: if it works in the terminal but not the VS Code or JetBrains extension, the IDE process didn't inherit your shell environment. Set the variables in the IDE's own settings, or launch the IDE from a terminal where they're already exported.

Performance and stability

The official troubleshooting docs also cover high CPU/memory usage and commands that hang or freeze as separate items. General prevention: keep Node updated, use a stable connection, and restart the session when stuck. Specific diagnostics depend on your environment, so see the relevant section of the official docs.

Summary

A quick check order: (1) confirm Node 18+, service status, and internet; (2) for install issues, refresh PATH → avoid sudo → use the native installer; (3) for auth, use the manual OAuth flow or an API key, and re-authenticate if needed; (4) for performance, update Node and restart the session. For more, see the official Claude Code troubleshooting docs.

The fixes here include only items confirmed in Claude's official docs (support.claude.com, code.claude.com). Symptoms and fixes can vary by environment (OS, network, IDE), so if it isn't resolved, use the official docs and support channels. (Official source: docs.claude.com)