Pricing

Claude Code "API Error: Unable to connect to API (ConnectionRefused)"

Q: How do I fix ConnectionRefused in the Claude Code VS Code extension?

Check whether `CLAUDE_CODE_SSE_PORT` is set; in open issue #91904 the CLI works once it's unset, but the reporter found no workaround for the panel itself.

Q: Why does curl work but Claude Code says ConnectionRefused?

The docs say a leftover `ANTHROPIC_BASE_URL` pointing at a dead local proxy or gateway causes exactly this; remove it and open a new terminal.

Claude Code says "Unable to connect to API (ConnectionRefused)"? The proxy, VS Code port and network causes users report, plus the documented fixes.

By Engineer Foodie Desk Nov 8, 2026 ✓ Sources checked Nov 8, 2026

8 min read

Error meaning, wording change and fixes checked Nov 8, 2026 in Anthropic’s Claude Code error reference and network configuration docs. Raw error strings quoted from Claude Code GitHub issues #84782, #78444, #78058, #76847 and #91904 (all verified Nov 8, 2026). Every source is listed at the bottom. No affiliate links on this page (how we work).

The exact error: `API Error: Unable to connect to API (ConnectionRefused)`

On older Claude Code builds, this is what you get. From #78444, #78058 and #76847 (v2.1.207 to v2.1.212; verified Nov 8, 2026):

API Error: Unable to connect to API (ConnectionRefused)

While it retries, the spinner version from #84782 (v2.1.224, verified Nov 8, 2026) looks like this:

✳ Unable to connect to API (ConnectionRefused) · Retrying in Ns · attempt N/10

On newer builds the same error reads differently. Anthropic’s error reference (verified Nov 8, 2026) gives the current string as:

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

and explains the change: “Before v2.1.227, each of these coded messages read Unable to connect to API followed by the code, for example Unable to connect to API (ECONNREFUSED).” The docs also note that “Connection refused can show ConnectionRefused or ECONNREFUSED”. #91904, on the VS Code extension v2.1.259, shows the new wording in the wild:

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

Same error, new paint job. If you’re searching the old string on a new build (or vice versa), you’re in the right place.

The one-line answer: the TCP connection never got made. The docs’ definition: “The TCP connection to the API failed or never completed.” Something between Claude Code and the API host refused the connection outright, which is different from a connection that opened and then dropped (that’s Claude Code ECONNRESET).

What causes it, per the docs and issues

The documented causes

The error reference lists: “Common causes include no internet access, a VPN that blocks api.anthropic.com, or a required corporate proxy that is not configured.” It also covers the frustrating case where curl works and Claude Code doesn’t: “a leftover value pointing at a local proxy or gateway that’s no longer running produces Connection refused even though curl reaches the API.” Other things on that list: an unreachable nameserver in /etc/resolv.conf on Linux and WSL, stale VPN utun interfaces on macOS, and Docker Desktop or similar runtimes that “can intercept outbound traffic.”

That leftover-proxy case is pure Super Mario Bros. Your shell reaches the castle fine, but Claude Code is knocking on a local gateway that shut down weeks ago. “Thank you Mario! But our princess is in another castle!”

Backgrounded or reconnected sessions skip your proxy (#78444)

#78444 (v2.1.212, Windows, PowerShell) explains it like this: “once a session has been backgrounded, it starts running under a different process context. … while it inherits most of the user’s environment variables, http_proxy and https_proxy are missing.” The repro: set the proxy variables at the user or system level, run /background, then “Re-open the session via claude agents or claude attach.” You have to go back, Lost-style, and the island has quietly forgotten your proxy settings.

It was closed as not_planned (stale) on Sep 8, 2026, with no maintainer fix.

`CLAUDE_CODE_SSE_PORT` in the VS Code extension (#91904)

#91904 (opened Sep 3, 2026, open with no maintainer reply as of Nov 8, 2026; labeled regression) says the “VS Code extension panel permanently fails with ConnectionRefused whenever CLAUDE_CODE_SSE_PORT is set, while the standalone CLI works fine without it.” The logs include:

[ERROR] Connection error details: code=ConnectionRefused, message=Unable to connect. Is the computer able to access the url?

After uninstalling local MCP tools (#78058)

#78058 (v2.1.210, Windows 11) started “right after” the reporter uninstalled several third-party MCP tools and ran CCleaner. Their cleanup included removing a “local proxy 127.0.0.1:8787 from the uninstalled headroom tool” from settings files, and they confirmed no HTTPS_PROXY or ANTHROPIC_BASE_URL in the environment. A full reinstall, including deleting ~/.claude, didn’t help. It was closed as “completed” on Jul 17, 2026 with no comment explaining a fix, so I can’t tell you what solved it, and I won’t pretend to.

No clear cause at all (#84782, #76847)

#84782 (v2.1.224, Windows 11) is the strange one: the interactive REPL failed on every message while claude --print "hello" “works instantly, every time”. The reporter ruled out proxy, VPN, hosts file and MCP servers. It closed as stale on Oct 6, 2026 with no maintainer reply.

#76847 (v2.1.207, macOS) ran “in a retry loop (up to 10 attempts) and then fails entirely”, even though curl to the API returned HTTP/2 405, meaning the host was reachable. Clearing ~/.claude and reinstalling “temporarily resolved, then recurred within the same day.” A collaborator closed it on Aug 20, 2026 as a duplicate of #75897, which I didn’t read.

Honestly, that’s a sad pile. Two of the clearest reports (#84782 and #78444) closed as stale, and one closed “completed” with no explanation. If you’re stuck on one of these, I feel you.

How to fix it, in order

Each step names where it comes from.

Let the retries finish. “Claude Code retries transient failures up to 10 times with exponential backoff before showing you an error” (errors doc, verified Nov 8, 2026). CLAUDE_CODE_MAX_RETRIES defaults to 10.
Test the host from the same shell. The docs: “Confirm you can reach the API host from the same shell by running curl -I https://api.anthropic.com. On Windows PowerShell use curl.exe -I https://api.anthropic.com”.
If curl works, hunt for a leftover base URL. Run echo $ANTHROPIC_BASE_URL (or echo $env:ANTHROPIC_BASE_URL in PowerShell) and check the env block of your settings files. If it points at a dead local proxy or gateway, “Remove it from your shell profile or settings and start Claude Code from a new terminal” (errors doc).
Configure your corporate proxy. “If you are behind a corporate proxy, set HTTPS_PROXY before launching Claude Code” and see the network configuration docs. If you deliberately use an LLM gateway, the docs say to “set ANTHROPIC_BASE_URL to its address.”
Backgrounded sessions: put the proxy in Claude settings. The #78444 reporter’s only stated workaround: “If they’re defined in Claude settings via env they do come through correctly.” That’s a user observation on v2.1.212, not an official fix.
VS Code: check CLAUDE_CODE_SSE_PORT. In #91904 the reporter ran Remove-Item Env:\CLAUDE_CODE_SSE_PORT in that shell, then claude again, and it “connects and works perfectly, every time.” For the panel itself they wrote: “Workaround: none for the VS Code panel itself.” So the CLI is your fallback while that issue is open.
Check firewall, VPN, DNS and containers. “Ensure your firewall allows the hosts listed in Network access requirements.” Then the docs’ other checks: /etc/resolv.conf on Linux and WSL, stale utun interfaces via ifconfig on macOS (remove the VPN’s network extension in System Settings), and quitting Docker Desktop to rule it out.
Still failing on an old build? The wording change landed in v2.1.227 per the docs, and every old-string issue above is on v2.1.207 to v2.1.224. I can’t promise updating fixes it (none of those issues says it did), but it does get you the clearer message.

What not to do: don’t chain random relays or “free API” proxies to get around a refused connection. If your network blocks api.anthropic.com, the legit fix is your network admin, a configured proxy or an approved gateway.

ConnectionRefused vs ECONNRESET vs 529

Error	Means	First move
ConnectionRefused	Never connected	curl, proxy, base URL
ECONNRESET	Connection dropped	ECONNRESET fixes
Timed out	No reply in time	Timeout fixes
529 Overloaded	API busy	529 fixes

ConnectionRefused row: errors doc, verified Nov 8, 2026. Other rows: same doc, as cited (with their own check dates) in our Claude Code ECONNRESET, Claude Code operation timed out and Claude Code 529 overloaded posts.

The short version: refused means the door was never opened, ECONNRESET means it opened and slammed mid-conversation, and 529 means you got through and Anthropic said “busy, try again.” The current docs list Connection dropped alongside Connection refused in the network section, so new builds name the two differently.

FAQ

What does Claude Code Unable to connect to API (ConnectionRefused) mean? The TCP connection to the API failed or never completed, per Anthropic’s error reference (verified Nov 8, 2026); builds before v2.1.227 used this wording.

What does Connection refused — a firewall or proxy may be blocking it (ConnectionRefused) mean? It’s the same error with the v2.1.227+ wording; common causes are no internet, a VPN blocking api.anthropic.com, or an unconfigured corporate proxy.

How do I fix ConnectionRefused in the Claude Code VS Code extension? Check whether CLAUDE_CODE_SSE_PORT is set; in open issue #91904 the CLI works once it’s unset, but the reporter found no workaround for the panel itself.

Why does curl work but Claude Code says ConnectionRefused? The docs say a leftover ANTHROPIC_BASE_URL pointing at a dead local proxy or gateway causes exactly this; remove it and open a new terminal.

Is ConnectionRefused the same as ECONNRESET? No. Refused means the connection never completed; ECONNRESET means it dropped after opening, and newer builds label that “Connection dropped”.

Here’s what I’d do

Run curl -I https://api.anthropic.com from the same terminal first. If it fails, it’s your network, VPN or proxy, and the docs’ checklist covers it. If it works, I’d go straight for echo $ANTHROPIC_BASE_URL and the settings env block, because a dead local gateway is the documented reason curl and Claude Code disagree. Using VS Code? Check CLAUDE_CODE_SSE_PORT before anything fancier.

If none of it helps and you have work to ship, keep a backup tool around. Claude Code alternatives and AI coding tools compared list the options with dated prices.

Sources

Claude Code error reference (§ Unable to connect to API / Network; current Connection refused — wording; v2.1.227 change; retries): https://code.claude.com/docs/en/errors (verified 2026-11-08)
Claude Code network configuration docs (HTTPS_PROXY): https://code.claude.com/docs/en/network-config (linked from the errors doc, 2026-11-08)
Claude Code GitHub issue #84782 (interactive REPL ConnectionRefused, v2.1.224; closed stale Oct 6, 2026): https://github.com/anthropics/claude-code/issues/84782 (verified 2026-11-08)
Claude Code GitHub issue #78444 (backgrounded sessions skip proxy, v2.1.212; closed stale Sep 8, 2026): https://github.com/anthropics/claude-code/issues/78444 (verified 2026-11-08)
Claude Code GitHub issue #78058 (after uninstalling MCP tools, v2.1.210; closed completed Jul 17, 2026, no fix stated): https://github.com/anthropics/claude-code/issues/78058 (verified 2026-11-08)
Claude Code GitHub issue #76847 (persistent on macOS, v2.1.207; closed duplicate Aug 20, 2026): https://github.com/anthropics/claude-code/issues/76847 (verified 2026-11-08)
Claude Code GitHub issue #91904 (CLAUDE_CODE_SSE_PORT in VS Code, v2.1.259, new wording; open): https://github.com/anthropics/claude-code/issues/91904 (verified 2026-11-08)

The exact error: API Error: Unable to connect to API (ConnectionRefused)