Troubleshooting

Claude Code Unable to connect to API: fix ECONNREFUSED, ECONNRESET, ENOTFOUND and timeouts

Published November 5, 2026 · Last checked November 5, 2026

Unable to connect to API means the connection from Claude Code to the API host failed or never completed, so the cause is almost always on the network path, not in your prompt. The parenthesised code tells you how it failed. This page explains what each code means, the checks that find the cause quickly, and how to set a proxy, a custom CA and the timeout variable. It follows Anthropic's Error reference and Enterprise network configuration, checked on November 5, 2026.

What each error code means

Claude Code keeps the code in parentheses so you can tell the failures apart. Anthropic lists these messages:

Unable to connect to API. Check your internet connection
Connection refused — a firewall or proxy may be blocking it (ConnectionRefused)
Can't reach the API server — check your internet or DNS (ENOTFOUND)
No internet route — check your connection or VPN (EHOSTUNREACH)
Couldn't connect through your proxy (ERR_PROXY_TUNNEL) — the proxy refused the tunnel: check its credentials and that it allows this host
Connection dropped (ECONNRESET)
Request timed out. Check your internet connection and proxy settings

On versions before v2.1.227 the same failures read Unable to connect to API (ECONNREFUSED), so you will see that older wording in search results and issue threads. Connection refused can show ConnectionRefused or ECONNREFUSED, and Can't reach the API server can show ENOTFOUND or FailedToOpenSocket.

The codes are standard Node.js system errors, defined in the Node.js error documentation:

The right-hand column is a starting point, not a diagnosis. The same code can come from more than one cause, which is why the next section checks the network path before changing settings.

Check the network path first

Anthropic's first step is to confirm you can reach the API host from the same shell where you run Claude Code:

curl -I https://api.anthropic.com

curl.exe -I https://api.anthropic.com

On PowerShell use curl.exe so the built-in Invoke-WebRequest alias is not used. If you send Claude Code through a relay or gateway, run the same check against its address: curl -I <your base URL>. Then go by the result:

• curl fails too. The problem is the network, not Claude Code. Check your internet access, your VPN, DNS and your firewall. Anthropic's list of hosts to allow is in Network access requirements.
• curl works but Claude Code still fails. Anthropic says the cause is usually something between the runtime and the network. Check the items below.

Look for a leftover ANTHROPIC_BASE_URL

When ANTHROPIC_BASE_URL is set, Claude Code sends model requests to that address instead of api.anthropic.com. A leftover value pointing at a local proxy or gateway that is no longer running produces Connection refused even though curl reaches the API. Check it with echo $ANTHROPIC_BASE_URL (echo $env:ANTHROPIC_BASE_URL in PowerShell) and look in the env block of your settings files. In Claude Code, /status shows the Base URL it is actually using. Remove a stale value from your shell profile or settings and start Claude Code from a new terminal.

Other local causes Anthropic lists

• On Linux and WSL, an unreachable nameserver in /etc/resolv.conf. WSL in particular can inherit a broken resolver from the host.
• On macOS, a disconnected or uninstalled VPN client can leave a tunnel interface or routing rule behind. Check ifconfig for stale utun interfaces.
• Docker Desktop and similar container runtimes can intercept outbound traffic. Quit them and retry to rule this out.

Intermittent failures are retried automatically, so a single blip does not need a fix.

Set a proxy, a CA or mTLS

Claude Code reads the standard proxy variables. Set them before you launch Claude Code; a running session does not pick up later changes to your shell environment. All of these can also go in the env block of settings.json.

# HTTPS proxy (recommended)
export HTTPS_PROXY=https://proxy.example.com:8080

# HTTP proxy (if HTTPS not available)
export HTTP_PROXY=http://proxy.example.com:8080

# Bypass the proxy for specific hosts
export NO_PROXY="localhost,192.168.1.1,example.com,.example.com"

Lowercase variants also work; Claude Code uses the first one set in the order https_proxy, HTTPS_PROXY, http_proxy, HTTP_PROXY. NO_PROXY accepts a space-separated or comma-separated list, and * bypasses the proxy for all requests. If the proxy needs basic authentication, put the credentials in the URL, as in http://username:password@proxy.example.com:8080, and avoid hardcoding the password in scripts. Claude Code does not support SOCKS proxies, so a SOCKS-only client has to expose an HTTP proxy port or be bypassed.

Claude Code stops launch with an error naming the variable when it cannot parse the proxy URL, for example one missing the http:// scheme. A wrong host or port is only found on the next request, which is when you see ECONNREFUSED or ERR_PROXY_TUNNEL.

For a corporate CA, point Node at the certificate file. By default Claude Code trusts its bundled Mozilla CA certificates and your operating system's certificate store:

export NODE_EXTRA_CA_CERTS=/path/to/ca-cert.pem

For client-certificate authentication, Anthropic documents CLAUDE_CODE_CLIENT_CERT, CLAUDE_CODE_CLIENT_KEY and, for an encrypted key, CLAUDE_CODE_CLIENT_KEY_PASSPHRASE. These are for enterprise setups; most people only need the proxy variables.

Confirm the settings loaded

Run /status in an interactive session. The Proxy row shows the active proxy URL and marks a value it cannot parse as invalid and ignored; the Additional CA cert(s) row shows the NODE_EXTRA_CA_CERTS path without checking that the file loaded. To see more, start with claude --debug. The log goes to ~/.claude/debug/<session-id>.txt and has lines such as CA certs: Appended extra certificates from NODE_EXTRA_CA_CERTS when the file loaded.

Timeouts and no response

Two messages are about waiting rather than connecting:

• Request timed out. The API did not respond before the connection deadline. The default is 10 minutes. Anthropic's advice: retry, and if a slow network or proxy is the cause, raise API_TIMEOUT_MS.
• No response from API. Claude Code sent a streaming request and got no response headers within the first-byte deadline. Claude Code sends it again, and the turn ends with this message when the retry also gets nothing. Anthropic says to send your message again, and if it repeats, treat it as a network or proxy problem. If a proxy or gateway on your network holds responses until they complete, raise API_TIMEOUT_MS so the retry waits longer.

API_TIMEOUT_MS is the time in milliseconds that each request attempt has to receive its response headers; the default is 600000. It does not limit how long a streaming response runs after that. To set it for one session:

export API_TIMEOUT_MS=1200000
claude

$env:API_TIMEOUT_MS = "1200000"
claude

Raising the timeout only helps when something is slow to answer. If the connection itself fails, it changes nothing.

First run: Unable to connect to Anthropic services

This one is a different message. During first-run setup, Claude Code checks that it can reach api.anthropic.com and platform.claude.com before showing the sign-in step. When a check fails, it prints the reason and exits, for example Failed to connect to api.anthropic.com: ECONNREFUSED or Connection to api.anthropic.com timed out after 10 seconds. The check goes through the same proxy configuration as API requests, and when the failed probe went through a proxy, the message names the variable, such as HTTPS_PROXY. Anthropic's advice is to check that the proxy value is right, run the same curl test as above, and note that Claude Code may not be available in your country.

If you use a relay, the first-run check is not about the relay at all: onboarding contacts Anthropic's services, which are often unreachable from mainland China. CoreCode's fix is to skip onboarding:

1. Open ~/.claude.json (on Windows, %USERPROFILE%\.claude.json) in an editor.
2. Add "hasCompletedOnboarding": true at the top level and save.
3. Run claude again.

The steps are the same as in CoreCode Errors and the FAQ.

With CoreCode: keep the relay direct

CoreCode is a relay answered by official Claude accounts. Claude Code points at it with ANTHROPIC_BASE_URL=https://corecode.live and the key in ANTHROPIC_AUTH_TOKEN, as shown in Claude Code. Run /status and confirm the Base URL reads https://corecode.live; if it does not, requests are going to the official host and a connection error there says nothing about the relay.

If a proxy or VPN is on, our guidance is that corecode.live is reachable directly from mainland China and a global proxy only sends requests the long way round: slower, and now and then a dropped stream. Add a DIRECT rule for corecode.live in your proxy client; Errors and Using Claude Code from mainland China say the same. This is the one place where a proxy rule for a relay is the fix. For a corporate proxy that all traffic must use, set HTTPS_PROXY as above instead.

If connection errors continue, check service status, then follow Feedback and contact. We do not promise availability.

FAQ

Sources

• Claude Code: Error reference (Unable to connect to API, Unable to connect to Anthropic services, Request timed out, No response from API; checked November 5, 2026)
• Claude Code: Enterprise network configuration (HTTPS_PROXY, HTTP_PROXY, NO_PROXY, no SOCKS support, NODE_EXTRA_CA_CERTS, mTLS variables, /status and --debug; checked November 5, 2026)
• Claude Code: Environment variables (API_TIMEOUT_MS; checked November 5, 2026)
• Node.js: Common system errors (ECONNREFUSED, ECONNRESET, ENOTFOUND, ETIMEDOUT; checked November 5, 2026)