"Connection refused — a firewall or proxy may be blocking it (ECONNREFUSED)"
Last checked
The error
API Error: Connection refused — a firewall or proxy may be blocking it (ECONNREFUSED)Claude Code's errors page lists it as Connection refused — a firewall or proxy may be blocking it (ConnectionRefused); the code can show as ConnectionRefused or ECONNREFUSED. Before v2.1.227 the same error read Unable to connect to API (ECONNREFUSED). The ✻ some terminals show in front is Claude Code's own status mark, not part of the error.
Claude Code tried to open a connection to the API and your operating system answered "refused": nothing was listening at the address and port it tried. It is almost never an Anthropic outage, which shows up as timeouts or 5xx errors instead. The usual cause is a leftover ANTHROPIC_BASE_URL pointing at a local proxy, gateway or Ollama that isn't running. Run echo $ANTHROPIC_BASE_URL and check the env block in your Claude Code settings files first.
Find your cause in 60 seconds
Run these in the same terminal where Claude Code fails, in order, and stop at the first one that tells you something. On Windows PowerShell use $env:ANTHROPIC_BASE_URL, $env:HTTPS_PROXY and curl.exe -I.
# 1. Is Claude Code being sent somewhere other than api.anthropic.com?
echo "BASE_URL=$ANTHROPIC_BASE_URL"
grep -r "ANTHROPIC_BASE_URL\|HTTPS_PROXY\|HTTP_PROXY" ~/.claude/settings.json .claude/settings.json .claude/settings.local.json 2>/dev/null
# 2. Can this machine reach the API at all?
curl -I https://api.anthropic.com
# 3. Is there a proxy in play?
echo "HTTPS_PROXY=$HTTPS_PROXY HTTP_PROXY=$HTTP_PROXY NO_PROXY=$NO_PROXY"
# 4. What does Claude Code itself report?
claude doctor| What you saw | Your cause | Go to |
|---|---|---|
| BASE_URL=http://127.0.0.1:… or localhost:… | Leftover base URL pointing at a local proxy, gateway or Ollama that isn't running | Cause 1 |
| BASE_URL empty, curl returns an HTTP status, Claude Code still fails | Something on this machine refuses one program but not another | Cause 4 / Cause 5 |
| curl also fails with Connection refused | Network-level block: corporate proxy needed, or a firewall on port 443 | Cause 2 |
| HTTPS_PROXY is a local address and curl fails | The local proxy itself isn't running or the port is wrong | Cause 1 / Cause 2 |
| You're in WSL, Docker or a container | DNS or networking inside the sandbox | Cause 3 |
| The error mentions 127.0.0.1:11434 or :1234 | Claude Code is pointed at Ollama or LM Studio and the server is down | Cause 6 |
Why it happens
A refusal this fast is local: the wrong address, a proxy that isn't running, or something on your machine or network refusing the connection. Claude Code's own errors page says a leftover base URL pointing at a local proxy or gateway that's no longer running produces Connection refused even though curl reaches the API.
- ANTHROPIC_BASE_URL points at a local address with nothing listening: an old Ollama, LM Studio, LiteLLM or Claude Code Router setup, a token-saving tool, or a company gateway. It hides in shell startup files, the env block of ~/.claude/settings.json or the project's .claude/settings.json, Windows machine-wide environment variables, or a systemd user session.
- You're behind a corporate proxy and Claude Code doesn't know about it, because HTTPS_PROXY isn't set where Claude Code runs.
- WSL, Docker or a dev container has its own DNS and routing, and that is what's broken.
- A firewall rule blocks the Claude Code program on port 443 while your browser and curl get through.
- Endpoint security, a VPN split tunnel or a content filter refuses one program but not another.
- You meant to use a local model (Ollama on 127.0.0.1:11434, LM Studio on :1234) and the server isn't running.
The fix
- 1 Run echo $ANTHROPIC_BASE_URL (PowerShell: echo $env:ANTHROPIC_BASE_URL) and check the env block of ~/.claude/settings.json, .claude/settings.json and .claude/settings.local.json. If it points at 127.0.0.1 or localhost and nothing is running there, remove it and open a new terminal.
- 2 To test that diagnosis without editing anything: env -u ANTHROPIC_BASE_URL -u ANTHROPIC_AUTH_TOKEN -u ANTHROPIC_API_KEY claude. If that works, the base URL was the cause.
- 3 Run curl -I https://api.anthropic.com. If curl also fails with connection refused, the network is blocking you: set HTTPS_PROXY (ask IT for the proxy address) and, if the proxy inspects TLS, NODE_EXTRA_CA_CERTS.
- 4 If curl works but Claude Code doesn't and no base URL is set, disconnect the VPN and retry, then check endpoint-security software and firewall rules for the claude or node binary.
- 5 In WSL, check /etc/resolv.conf for an unreachable nameserver. On macOS, look for stale utun interfaces from a VPN. Quit Docker Desktop and retry.
- 6 Run claude doctor, then claude -p "say ok" to confirm one request goes through.
echo $ANTHROPIC_BASE_URLCause 1: ANTHROPIC_BASE_URL points at a local address that isn't listening
By far the most common cause. At some point you, or a tool you installed, set ANTHROPIC_BASE_URL to route Claude Code through something local: Ollama at http://localhost:11434, LM Studio at :1234, a LiteLLM or Claude Code Router proxy at :4000 or :8787, a token-saving tool, a company gateway. That thing is no longer running, but the variable is still set, so every request goes to a closed port and is refused instantly.
Users on the Claude Code issue tracker have found it in all of these places: ~/.zshrc, ~/.bashrc and ~/.profile; the env block of ~/.claude/settings.json, written there by a third-party tool; a machine-wide Windows environment variable pushed by a corporate image; and a systemd user session that inherited Ollama's base URL (systemctl --user show-environment | grep ANTHROPIC shows it).
Remove the line, or point it at something that's running, then open a new terminal. Settings-file values apply even when your shell is clean, so check the JSON files too; /status inside Claude Code shows which base URL is in effect.
# Confirm the diagnosis without editing anything
env -u ANTHROPIC_BASE_URL -u ANTHROPIC_AUTH_TOKEN -u ANTHROPIC_API_KEY claudeCause 2: You're behind a corporate proxy and Claude Code doesn't know
On a managed laptop, outbound HTTPS often has to go through a proxy. Browsers get it from system settings; Claude Code doesn't. Without HTTPS_PROXY it connects to api.anthropic.com:443 directly and the network refuses. Set the proxy in the terminal that runs Claude Code, or in the env block of ~/.claude/settings.json so the CLI and the VS Code extension both see it.
export HTTPS_PROXY=http://proxy.yourcompany.com:8080
export HTTP_PROXY=http://proxy.yourcompany.com:8080
export NO_PROXY=localhost,127.0.0.1
# If the proxy inspects TLS with a company certificate:
export NODE_EXTRA_CA_CERTS=/path/to/company-root.pemAsk IT for the proxy address and the root certificate, and to allowlist the hosts in Claude Code's network access requirements (api.anthropic.com and claude.ai first; the full list is in the network configuration docs linked below).
A local authenticating proxy such as CNTLM or Px on 127.0.0.1:3128 counts as a local address: if it isn't running, you're back in Cause 1. One open issue (#98367) reports the VS Code extension working through CNTLM while the CLI fails; there's no confirmed fix for that exact case yet.
Cause 3: WSL, Docker or a dev container
WSL: check /etc/resolv.conf for a nameserver that doesn't answer, which is common after a VPN connects; WSL can inherit a broken resolver from the host. Set generateResolvConf = false under [network] in /etc/wsl.conf, write a working nameserver to /etc/resolv.conf, then run wsl --shutdown from Windows and reopen.
Docker Desktop: Claude Code's docs note that Docker Desktop and similar container runtimes can intercept outbound traffic. Quit it and retry as a quick test.
Dev containers and CI: pass HTTPS_PROXY and your API key into the container explicitly. A container doesn't inherit your shell.
Cause 4: A firewall rule on the Claude Code program
On locked-down machines, Windows Defender Firewall or a third-party suite can block outbound connections for one executable. The tell: curl and the browser work, claude doesn't, even with no base URL and no proxy. On Windows check Allow an app through firewall for node.exe or claude.exe; on macOS, check Little Snitch or LuLu for a denied rule on claude or node.
Cause 5: Endpoint security or a VPN split tunnel
A Claude Code maintainer explained on GitHub (#82777) that ConnectionRefused isn't a generic bucket: it's the actual socket error the OS returned. Refusals that fast are local, and per-application network filters (endpoint security, VPN split-tunnel rules, content filters) commonly allow curl while refusing a different binary.
Disconnect the VPN and retry; if it works, it's split tunnelling or the VPN's DNS. On macOS a stale VPN interface can linger after disconnecting: ifconfig | grep utun lists them, and removing the VPN's network extension in System Settings or a reboot clears them. If it's not the VPN, ask IT to allow api.anthropic.com for the Claude Code process in your endpoint-security tool. Nothing inside Claude Code bypasses this.
Cause 6: You meant to use a local model and it isn't running
If the message mentions 127.0.0.1:11434 (Ollama) or :1234 (LM Studio), the base URL is intentional and the server is simply down. Start it (ollama serve, or start the server in LM Studio), confirm with curl http://127.0.0.1:11434/v1/models, and run Claude Code again. For the other ways Ollama refuses connections, and for fetch failed errors in general, see the guides below.
Prove it's fixed
Run these three. If claude -p returns text, you're done. If you now get a 401 or 403, the connection works and the key is the problem, which is a different error.
curl -I https://api.anthropic.com # or your gateway URL: an HTTP status, not "refused"
claude doctor # diagnostics without starting a session
claude -p "say ok" # one real requestStill failing?
- Run claude doctor and /status and compare the base URL they show with what you expect.
- The CLI and the VS Code extension read different environments: the extension inherits VS Code's (often launched without your shell exports), the CLI inherits the terminal's. Put ANTHROPIC_BASE_URL and HTTPS_PROXY in ~/.claude/settings.json so both see the same values.
- If the first-run login says Unable to connect to Anthropic services with ECONNREFUSED, the same causes apply.
Related errors
Hit a different error?
Paste any agent error and get the cause and fix in seconds.
Frequently asked questions
Is "Connection refused — a firewall or proxy may be blocking it" an Anthropic outage?
Almost never. An outage shows up as timeouts, 529 overloaded or 5xx errors. Connection refused is your operating system reporting that nothing accepted the connection, before any request reaches Anthropic. Check echo $ANTHROPIC_BASE_URL first; a leftover local address is the usual cause. status.anthropic.com rules out an outage if you want to be sure.
Why does it only happen on my work laptop?
Work machines add the three things that cause it: a corporate proxy Claude Code needs HTTPS_PROXY to use, endpoint-security or VPN rules that can refuse one program while allowing another, and environment variables set by the company image, including, in at least one reported case, a machine-wide ANTHROPIC_BASE_URL. Run the 60-second check on that laptop.
What does the ✻ before the message mean?
Nothing. It's Claude Code's own status mark in the terminal. The error is the text after it, and ECONNREFUSED and ConnectionRefused mean the same thing.
curl works but Claude Code still says connection refused. Why?
Either Claude Code isn't talking to the same address as curl, because an ANTHROPIC_BASE_URL in a settings file points at a local proxy that isn't running, or a per-application filter such as endpoint security or a VPN split tunnel allows curl but refuses the Claude Code binary. Test with env -u ANTHROPIC_BASE_URL claude, then with the VPN disconnected.
I set HTTPS_PROXY and now get a certificate error instead.
Progress: the connection now reaches the proxy, which inspects TLS with a company certificate Node doesn't trust. Export the company root certificate as a .pem, set NODE_EXTRA_CA_CERTS to its path in the same environment, and retry.
Does this happen with the VS Code extension too?
It can, and sometimes only one of the two fails, because the extension inherits VS Code's environment while the CLI inherits the terminal's. Compare ANTHROPIC_BASE_URL and HTTPS_PROXY in each, and put them in ~/.claude/settings.json so both see the same values.
Stop firefighting agent errors
Decoding errors one at a time is the manual version of what BetterClaw automates. Run your agents on a no-code AI agent platform with managed models, retries and config validation built in.
Free plan available · Pro $49/mo · BYOK · 7-day free trial
