OmniscioGuidesECONNREFUSED
Claude Code: connection refused (ECONNREFUSED)
Last checked against Anthropic's documentation on November 14, 2026. By the Omniscio team. Updated .
What should I try first?
Anthropic names three common causes for this error. Work through them in order, and stop when it starts working.
- Check you are online. Open a website in your browser. No internet access is one of the three causes.
- Turn off your VPN and try again. A VPN that blocks
api.anthropic.comis the second cause. If you need the VPN on, that is the conversation to have with whoever runs it. - On a company computer or network, ask for help. A required company proxy that is not set up is the third cause. Hand this page to whoever manages your network; the firewall list they need is linked at the bottom.
- If you once set a proxy or a custom server address, undo it. The last section shows how to check, and it is the reason this error happens when everything else looks fine.
What does the message look like?
Current versions name the kind of failure and keep the code in parentheses:
Connection refused — a firewall or proxy may be blocking it (ConnectionRefused)The message can show the code as ECONNREFUSED instead. Before v2.1.227 the line read:
Unable to connect to API (ECONNREFUSED)During first-run setup there is a third form, printed before Claude Code asks you to sign in:
Failed to connect to api.anthropic.com: ECONNREFUSEDWhat does ECONNREFUSED actually mean?
It means something answered and said no. The other computer was found, and it refused the connection.
That rules a few things out, which is useful:
- It is not a name lookup problem.
ENOTFOUNDis that one: no address was found at all. - It is not a dropped connection.
ECONNRESETis that one: a working connection was cut. - It is not your login. Your key, your account and the model were never reached.
Where do I type the commands on this page?
There are two different places, and it matters which one you use.
- The chat box is where you type messages to Claude. Commands such as
/compactand/cleargo there, with a slash in front, then Enter. - A terminal is the separate black window where you type raw commands such as
curlandecho. The checks below need a terminal.
If you do not use a terminal, you can skip the next section. The steps above are the ones that apply to you.
If you are comfortable in a terminal, what finds the cause?
Start with the leftover address. It is the cause Anthropic calls out, and it is easy to miss.
When ANTHROPIC_BASE_URL is set, Claude Code sends requests to that address instead of api.anthropic.com. If it points at a local proxy or gateway that is no longer running, every request is refused, even though curl reaches the real API.
Check it with echo $ANTHROPIC_BASE_URL, or echo $env:ANTHROPIC_BASE_URL in PowerShell. Also look for it in the env block of your settings files. If it points somewhere you do not recognise, remove it, open a new terminal, and start Claude Code again.
If that was not it, work down this list. Each step tests one link in the chain.
- Test the API from the same shell. Run
curl -I https://api.anthropic.com, orcurl.exe -I https://api.anthropic.comin PowerShell so the built-in alias is not used. If that fails too, the problem is the network rather than Claude Code. - Set the proxy. Behind a company proxy, set
HTTPS_PROXYbefore launching Claude Code, for exampleHTTPS_PROXY=http://proxy.company.com:8080 claude. The corporate proxy guide walks through the rest. - Check the firewall. The hosts Claude Code needs are on Anthropic's network configuration page. Hand that list to whoever manages your network.
- Rule out a VPN left behind. A VPN that was disconnected or uninstalled can leave a route in place. On macOS, check
ifconfigfor staleutuninterfaces. - Rule out a container runtime. Docker Desktop and similar runtimes can intercept outbound traffic. Quit them and retry.
Does Claude Code retry this on its own?
It retries transient failures on its own, up to 10 times with exponential backoff. A refused connection is not transient, because nothing is listening.
So it keeps failing until the cause is fixed. Waiting will not clear it.
Common questions
What does ECONNREFUSED mean in Claude Code?
Something answered and said no. The address resolved, so DNS worked. A machine was reached and it refused the connection. That is different from ENOTFOUND, where no address was found at all, and from ECONNRESET, where a working connection was cut.
What should I try first if I am not technical?
Check you are online. If a VPN is switched on, turn it off and try again. If you are on a company computer or a company network, hand this page to whoever manages it, because a firewall or a proxy is refusing the connection. All three are causes Anthropic names.
Why does it happen when curl works fine?
A common cause, when curl still works, is a leftover ANTHROPIC_BASE_URL. When that variable is set, Claude Code sends model requests to that address instead of api.anthropic.com. If it points at a local proxy or gateway that is no longer running, every request is refused even though curl reaches the real API.
Does Claude Code retry a refused connection?
It retries transient failures on its own, up to 10 times with exponential backoff. A refused connection is not transient: nothing is listening. It keeps failing until the cause is fixed.
Where these answers come from
- Claude Code error reference, for the message forms, the three common causes, the
curltest, theANTHROPIC_BASE_URLcheck and the firewall list. Read November 14, 2026. - The same page's first-run check entry, for
Failed to connect to api.anthropic.com: ECONNREFUSED. - The same page's retry section, for the 10 retries and the backoff.
- Our connection errors guide covers the whole family, and the ECONNRESET page covers the dropped-connection sibling.