GrepBoard/Manuals
51 manuals ·

Fix common Claude Code errors by message

·Claude Code 2.1.302 · Ubuntu 24.04·7 steps

Match a Claude Code error — Invalid API key, Not logged in, 529, connection refused, certificate errors — to its cause and fix it with env vars and settings.

Find the error text on your screen in the steps below and apply the fix.

[1] Check the installation first. Run claude doctor in a shell if claude won't start, or /doctor inside a session.

console
$ claude --version2.1.302 (Claude Code)$ claude doctorClaude Code doctor Running: npm-global (2.1.302)Platform: linux-x64Search: OK (bundled)Auto-updates: enabledAuto-update channel: latest No installation issues found.

[2] Not logged in · Please run /login means there are no credentials. Run /login in an interactive session.

console
$ claude -p hi --max-turns 1Not logged in · Please run /login

[3] Invalid API key · Fix external API key means the value in ANTHROPIC_API_KEY is wrong. Find where it is set, and unset it to use your subscription login.

console
$ ANTHROPIC_API_KEY=sk-ant-invalid claude -p hi --max-turns 1Invalid API key · Fix external API key$ grep -n ANTHROPIC_API_KEY ~/.zshrc ~/.bashrc ~/.profile$ unset ANTHROPIC_API_KEY

[4] API Error: Repeated 529 Overloaded errors means the API is at capacity. It is unrelated to your usage limit.

  • Check status.claude.com for capacity notices.
  • Try again in a few minutes.
  • Run /model and pick another model. Capacity is tracked per model. You may see a hint such as Opus is experiencing high load, please use /model to switch to Sonnet.

[5] Connection refused — a firewall or proxy may be blocking it (ECONNREFUSED) means a proxy or firewall is in the way. Behind a corporate proxy, set HTTPS_PROXY. The value must start with http://; SOCKS is not supported. The last command points at a dead proxy (127.0.0.1:9) to reproduce the message.

console
$ export HTTPS_PROXY=http://proxy.example.com:8080$ export NO_PROXY="localhost,example.com"$ HTTPS_PROXY=http://127.0.0.1:9 CLAUDE_CODE_MAX_RETRIES=1 claude -p hi --max-turns 1API Error: Connection refused — a firewall or proxy may be blocking it (ECONNREFUSED)

[6] If a TLS-inspecting proxy causes unable to get local issuer certificate, SELF_SIGNED_CERT_IN_CHAIN, or SSL certificate verification failed, make Claude Code trust your corporate root certificate.

console
$ export NODE_EXTRA_CA_CERTS=/etc/ssl/certs/corp-ca.pem$ claude --debug

[7] To avoid exporting variables in every shell, put them in the env block of a settings file. Locations, highest priority first:

~/.claude/settings.json
{"env": {  "HTTPS_PROXY": "http://proxy.example.com:8080",  "NODE_EXTRA_CA_CERTS": "/etc/ssl/certs/corp-ca.pem"}}
  • Managed settings (your organization) — highest
  • claude --settings — this session only
  • .claude/settings.local.json — this project, you only
  • .claude/settings.json — this project, everyone
  • ~/.claude/settings.json — all projects, you only

#claude-code#troubleshooting