Claude Code Not Working? Fix Install, Auth & Connection Errors

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. (Commands and requirements may change, so check the official docs for the latest.)

Check these basics first

• Node version: as of September 2026 the official setup docs list no Node.js requirement — the native installer (recommended) runs without Node.js. Only npm install -g requires Node.js 22 or later (since v2.1.198); on an older version npm prints an EBADENGINE warning but the install completes and claude still runs (the binary is native and does not use Node at runtime). Check with node -v.
• 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.
• WSL runs Windows Node instead of Linux Node: in WSL, claude sometimes picks up the Windows Node instead of the Linux one. The Windows PATH is leaking into WSL and overriding nvm — prepend your Linux node in ~/.bashrc: export PATH="$HOME/.nvm/versions/node/$(nvm current)/bin:$PATH"

# Check Node version (npm install only, 22 or later)
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 official docs list three common causes. (1) 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; (2) you previously ran /login and the OAuth session is taking precedence — run /logout first; (3) the key is a Console key but your organization requires SSO login instead.
• Bedrock / Vertex "could not load credentials": Claude Code uses the standard provider SDKs, so the fix is the same as for any AWS/GCP CLI tool. For Bedrock, confirm aws sts get-caller-identity works and AWS_REGION is set to a region where your model is enabled. For Vertex, confirm gcloud auth application-default login has been run and GOOGLE_CLOUD_PROJECT is set.
• 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.
• Installed and authenticated, but every request errors with 403 / "model not available": your account exists but lacks access to the model Claude Code is requesting. For Enterprise seats, confirm your seat is active in your organization's admin settings; on Bedrock or Vertex, confirm the specific Claude model is enabled in that region or project. A quick workaround is to run /model and pick a model you have access to.

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 your install method (native needs no Node; npm needs Node 22+), 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.

Frequently asked questions

Claude Code will not install.

If the command is not found after install, refresh your PATH. Installing with sudo is not recommended; if it is stuck, use the native installer — that is the official order. (The native install needs no Node.js.)

I cannot log in (auth fails).

Use the manual OAuth flow or authenticate with an API key. If it still fails, re-authenticate (log out and back in).

Which Node version do I need?

As of September 2026, Node.js is not a system requirement in the official docs. The native installer runs without Node.js; only the npm install route requires Node.js 22+ (since v2.1.198), and older versions only trigger a warning while the install and claude still work. The older "Node 18+" guidance no longer applies.

Is there a diagnostic tool?

Run claude doctor to print a diagnostic report. Attaching it to a support ticket speeds up root-cause analysis.

Claude Code is slow or freezes.

The official docs treat high CPU/memory and hang/freeze as separate items. Keep Node up to date, use a stable internet connection, and restart the session when it stalls.

Learn more: control allow and deny rules and permission modes with Claude Code permissions.

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: support.claude.com, code.claude.com)

New here?: How to Read Error Messages (beginner)

Quick Diagnosis: Find Your Error in 30 Seconds

Before diving into individual fixes, match your symptom to the right section. Most Claude Code problems belong to one of four buckets:

The Four Most Common Fixes (Step-by-Step)

Fix 1 — command not found: PATH not updated

What happened: npm installed Claude Code globally, but your shell does not know where to find it yet.

Step 1. Run the install command if you have not already (check the official getting-started page for the current package name — it may change):

npm install -g @anthropic-ai/claude-code

Step 2. Find where npm puts global binaries:

npm config get prefix

Step 3. Add the /bin subfolder of that path to your shell profile. For bash or zsh on macOS/Linux, open ~/.zshrc or ~/.bashrc and add (replace /usr/local with the path from Step 2 if different):

export PATH="$PATH:/usr/local/bin"

Step 4. Reload the profile, then confirm:

source ~/.zshrc
claude --version

✅ Success signal: A version number prints. If you still see command not found, double-check that the path from Step 2 ends in /bin and matches what you added.

Fix 2 — Install fails: Node.js version too old

What happened: if you installed via npm, the package requires a minimum Node.js version (Node.js 22+ since v2.1.198, as of September 2026; the native installer needs no Node.js — verify the current minimum on the official docs).

Step 1. Check your current version:

node --version

Step 2. If the number is below the required minimum, install a newer version via nodejs.org or a version manager such as nvm. Then re-run the install from Fix 1, Step 1.

✅ Success signal: npm install completes without ERR! lines.

Fix 3 — Login never completes: OAuth callback blocked

What happened: Claude Code opens your browser for login, but the redirect back to localhost is blocked by a browser extension, firewall, or security tool.

1. Temporarily disable ad-blockers or security extensions in your browser.
2. Make sure nothing on your machine is blocking localhost connections.
3. If a corporate firewall is involved, ask your IT team to allow the localhost callback port shown in your terminal output.
4. Re-run claude to restart the auth flow.

✅ Success signal: Terminal prints a confirmation that you are logged in and returns a prompt.

Fix 4 — SSL/certificate error on a corporate network

What happened: Your company proxy re-signs TLS traffic with an internal CA that Claude Code does not trust by default.

1. Obtain your company's root certificate file (ask IT — usually a .pem or .crt file).
2. Point Node.js to it before running Claude Code. The environment variable name may vary — check the official troubleshooting page for the exact variable name currently supported.
3. Re-run claude in the same terminal session.

✅ Success signal: No more certificate errors; the login flow proceeds normally.

If you are stuck at the install or login stage specifically, start with the dedicated Claude Code install and login troubleshooting guide.

Related articles

• Claude Code Running Slow or Freezing: Performance & /doctor Diagnostics
• How to Read Claude Code Error Messages — A Beginner's Guide
• Claude Code Install & Login Errors: Step-by-Step Fix Guide
• Claude Code Skill Not Recognized — Troubleshooting Guide
• Claude Code Installation Guide: native vs npm, Windows Included