API Error: Connection refused — a firewall or proxy may be blocking it (ConnectionRefused)

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://gist.github.com/SerkanAy/3bba963e8bf564a858ebb3beff661cc1

Section/Topic

API Error:Connection refused

Current Documentation

Claude Code — "Connection Refused" Fault Log
Date: 2026-08-17 Machine: Kali Linux (Debian-based), local dev workstation Claude Code version: 2.1.233

Symptom
API Error: Connection refused — a firewall or proxy may be blocking it (ConnectionRefused)

Persisted across:

claude update (already up to date)
Native installer AND fresh npm install
With and without --debug
Regardless of IPv4/IPv6 forcing
Root Cause
ANTHROPIC_BASE_URL was set to a dead local endpoint:

ANTHROPIC_BASE_URL="http://127.0.0.1:8787"

Found in three shell config files:

~/.bashrc
~/.zshrc
~/.profile

Nothing was ever listening on port 8787 (lsof -i :8787 returned empty). Claude Code was sending every request to this dead local port instead of api.anthropic.com, so the connection was refused instantly — before it ever left the machine.

This is why standard network diagnostics gave false negatives:

curl -v https://api.anthropic.com/v1/messages → succeeded (curl doesn't read ANTHROPIC_BASE_URL)
node -e "fetch('https://api.anthropic.com/v1/messages')..." → succeeded (raw fetch doesn't read it either)
Only Claude Code itself was affected, because it's the only tool that respects that env var
Diagnostic Path (what ruled things out, in order)
curl -v https://api.anthropic.com/v1/messages → TLS/network fine, got 405 (expected — GET isn't valid on that endpoint)
env | grep -i proxy → empty, no proxy env vars
curl -v -4 ... → ruled out IPv6-specific Node bug
Debug logs (~/.claude/debug/latest) → showed mTLS init lines (red herring, just boilerplate) but never captured the actual failed request
Checked for Kali-specific interception: /etc/ld.so.preload (absent — ruled out system-wide hijacking), proxychains config present but not force-loaded, no aliases wrapping node/claude
node -e "fetch(...)" direct test → succeeded, proved Node's networking stack was fine
claude doctor → surfaced the actual cause directly:

"ANTHROPIC_BASE_URL is set and does not point at api.anthropic.com"
Fix
sed -i '/ANTHROPIC_BASE_URL/d' ~/.bashrc ~/.zshrc ~/.profile

unset ANTHROPIC_BASE_URL

Then open a new terminal session (old shells keep the var in memory even after the file edit) and confirm:

echo $ANTHROPIC_BASE_URL # should print nothing

claude # should connect normally
Lesson / Fast Path for Next Time
Run claude doctor early — it directly reports ANTHROPIC_BASE_URL misconfiguration and multiple-installation conflicts. This would have identified the fault in one command instead of a long manual network diagnostic chain (curl, env, IPv4/IPv6, debug logs, Kali interception checks, raw Node fetch test).

Secondary finding (unresolved, low priority): claude doctor also flagged two parallel installations:

npm-global at ~/.config/nvm/versions/node/v22.23.2/bin/claude
native at ~/.local/bin/claude

Not the cause of this fault, but worth cleaning up later to avoid version drift between the two.

What's Wrong or Missing?

claude-code-connection-refused-fault.md

Suggested Improvement

claude-code-connection-refused-fault.md

Impact

High - Prevents users from using a feature

Additional Context

_No response_