Claude Code Connection Error: DNS, TLS, and Proxy Fixes

A claude code connection error means the request never completed a network round trip — DNS, TCP or TLS failed before Anthropic could answer. It is a transport problem, not a login or quota problem, so triage the network path: proxy, TLS inspection, VPN, firewall, DNS, then any custom gateway URL.

Network and certificate behavior verified 31 July 2026 against Anthropic’s Claude Code network configuration docs.

That one distinction saves most of the time people waste on this. API Error: Connection error is not 401, not 429, not 529. Those three mean your packets arrived and a server chose to answer with a refusal. A connection error means nothing came back at all. So stop rechecking your API key and start checking the wire. We put this through its paces on our own setup first, so the notes below reflect what really happened, not what should happen.

First, rule out the obvious in 60 seconds

Answer one question before editing anything: Anthropic, or you? Check the status page, run a bare curl against the API host, then retry on a phone hotspot. Three checks, sixty seconds, whole classes of cause eliminated.

Before you touch a config file, answer one question: is it Anthropic, or is it you?

1. Open status.anthropic.com and look for an active incident on the Claude API.
2. Run a plain curl against the API host from the same terminal that produced the error.
3. Try a second network — a phone hotspot is the fastest way to swap every variable at once.

If status is green and the hotspot works, the fault is in your local network path, and the rest of this guide is your map. If the hotspot fails too, you're looking at something machine-level: DNS, a certificate store, or an environment variable that follows you everywhere.

One more sanity note before you dig in. Model choice is irrelevant here — a claude code connection error hits the transport layer identically whether you're currently on Claude Opus 5 or Claude Haiku 4.5, because the failure happens before any model is selected. If swapping models "fixes" it, you got lucky with a retry, not a diagnosis.

What a claude code connection error actually is

A failure in DNS, TCP, or TLS — the three layers that must clear before HTTP exists at all. That is why there is no status code to search for, and why four short commands can isolate it.

Every Claude Code request has to clear four layers before a model ever sees it:

• DNS — api.anthropic.com has to resolve to an address.
• TCP — port 443 has to open to that address.
• TLS — the certificate the server presents has to chain to a CA your machine trusts.
• HTTP — only now do you get status codes, and only now can you get a 401 or 429.

A claude code connection error is a failure somewhere in the first three. That's why it feels so opaque: there's no status code to google. The good news is that four layers is a short list, and each one has a command that proves or clears it.

What causes a claude code connection error?

Five culprits account for nearly all of them: a TLS-inspecting corporate proxy, a VPN with split tunnelling, a firewall allowlist missing the API domain, DNS or IPv6 quirks, and a stale custom base URL.

1. A corporate proxy doing TLS inspection

This is the number one cause on managed laptops, and it's sneaky because your browser works fine. A TLS-inspecting middlebox terminates the connection, reads it, and re-signs it with a private corporate CA. Your browser trusts that CA because IT pushed it into the OS store years ago. Node-based tooling may not.

Claude Code trusts both its bundled Mozilla CA set and your OS certificate store, but reading the OS store needs a runtime with tls.getCACertificates — the native installer always has it, while npm installs need Node 22.15 or later. On older Node, only the bundled set plus NODE_EXTRA_CA_CERTS apply, which is exactly how a machine that "works in Chrome" throws unable to get local issuer certificate or SELF_SIGNED_CERT_IN_CHAIN in the CLI.

Two fixes, per Anthropic's enterprise network configuration docs:

# Trust your corporate CA bundle
export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem
 
# Route through the proxy (HTTPS_PROXY is the one that matters)
export HTTPS_PROXY=http://proxy.example.com:8080
export HTTP_PROXY=http://proxy.example.com:8080
export NO_PROXY="localhost,127.0.0.1,.internal.example.com"

Two gotchas worth knowing. NO_PROXY accepts both space-separated and comma-separated values, and * bypasses the proxy entirely. And SOCKS proxies aren't supported — if your only proxy is SOCKS, no environment variable will save you.

If your proxy needs mutual TLS, CLAUDE_CODE_CLIENT_CERT and CLAUDE_CODE_CLIENT_KEY (plus CLAUDE_CODE_CLIENT_KEY_PASSPHRASE for an encrypted key) exist for that. Don't set them speculatively; they're for environments where IT told you client certs are mandatory.

2. VPN and split tunnelling

A VPN is the second-most-common source of a claude code connection error, and split tunnelling makes it worse because the failure is partial. Traffic to your internal hosts goes down the tunnel, traffic to the public internet goes direct — and whichever path api.anthropic.com lands on may be the blocked one. Disconnect the VPN and retry. If the error vanishes, you've found your layer, and the conversation moves to your network team.

3. A firewall blocking the API domain

Locked-down networks and containers frequently allowlist by domain. Claude Code needs api.anthropic.com for API requests, and depending on how you sign in, also claude.ai or platform.claude.com for authentication, plus downloads.claude.ai for the native installer and auto-updater. A firewall that allows the login hosts but not the API host produces the most confusing version of this: you log in successfully, then every prompt dies. If you also see the CLI blocked by local endpoint security rather than the network, Claude Code and Bitdefender covers that pattern.

4. DNS and IPv6 quirks

If api.anthropic.com doesn't resolve, nothing else matters. Split-horizon DNS on a corporate network, a stale resolver cache, or a broken IPv6 route that times out before falling back to IPv4 will all surface as a generic connection error. Test resolution directly rather than assuming it works. Browser-side failures like can't reach Claude often share the same DNS root cause as the CLI version.

5. A custom ANTHROPIC_BASE_URL pointing somewhere dead

ANTHROPIC_BASE_URL overrides the API endpoint so you can route through a proxy or LLM gateway. Set it once for an experiment, forget it, and every later session quietly aims at a host that may be offline. Check it before anything else if you've ever touched a gateway. Same story for ANTHROPIC_AWS_BASE_URL, ANTHROPIC_BEDROCK_BASE_URL, ANTHROPIC_VERTEX_BASE_URL and ANTHROPIC_FOUNDRY_BASE_URL on those platforms — a stale override sends every request to a host that stopped existing.

The triage table

Match the symptom to the layer. Certificate wording points at TLS inspection, hotspot-versus-office points at a proxy or firewall, Could not resolve host points at DNS, and a hang on large requests points at timeouts or buffering.

Test each layer instead of guessing

Four commands settle it: nslookup for DNS, a bare curl to the messages endpoint for TCP, TLS and HTTP together, a verbose curl for the certificate issuer, and env for whatever your shell is injecting.

Guessing costs hours. Four commands cost a minute. Run these from the same shell where claude fails — that detail matters more than people expect.

# 1. DNS: does the host resolve at all?
nslookup api.anthropic.com
 
# 2. TCP + TLS + HTTP: a 401 here is a SUCCESS. It means the wire works.
curl -sS -o /dev/null -w "%{http_code}\n" https://api.anthropic.com/v1/messages
 
# 3. Certificate chain: who signed what you're actually being handed?
curl -vI https://api.anthropic.com 2>&1 | grep -Ei "issuer|subject|SSL"
 
# 4. What is this shell actually telling Claude Code to do?
env | grep -Ei "proxy|anthropic|node_extra|cert"

Read step 2 carefully, because it's the pivot of the whole triage. If curl prints 401, your DNS, TCP and TLS are all fine and the network is exonerated — you've now got an auth or config problem, not a claude code connection error. If curl prints nothing or hangs, the network is guilty and steps 1, 3 and 4 will tell you which layer.

This "401 is success" reframe is the single habit that changed how we debug these on our own machines. For a long time our reflex on any connection error was to start re-checking the API key — which, as this whole guide argues, is the one thing it never is. Now the first thing we run is that bare curl against the messages endpoint, and the moment it returns a status code at all we stop touching the network and go read config instead. It sounds trivial written down, but on Windows especially — where PowerShell quietly aliases curl to something that rejects these flags — proving the wire works before changing anything has saved us more wasted evenings than any single row in the table above.

Step 3 is the giveaway for TLS inspection: if the issuer says your company's name instead of a public CA, a middlebox is in the path and NODE_EXTRA_CA_CERTS is your fix. Note that on Windows PowerShell you need curl.exe, not curl — PowerShell aliases curl to Invoke-WebRequest, which rejects these flags.

The settings.json vs shell env gotcha

Every network variable can live in a shell export or in the env block of settings.json, so the two drift apart silently. Read both side by side and keep exactly one source of truth.

Here's the claude code connection error that burns experienced engineers. Every network variable on that docs page can also live in the env block of settings.json. So you can have a proxy set in one place and not the other, and the result depends on which one wins and where you launched from.

The classic shapes of this bug:

• You export HTTPS_PROXY in your terminal, it works, then the VS Code extension fails — the IDE process never inherited your shell environment. Launch the IDE from a terminal where the variables are exported, or set them in the IDE's own settings.
• Your settings.json has a proxy from a job you left. Every new shell looks clean, but Claude Code still routes through a dead host.
• You set a variable in ~/.zshrc while your default shell is Bash — for example, the export never runs, and the value only appears when you manually open zsh.

Run env | grep -i proxy and read your settings.json env block side by side. One truth, one place. CLAUDE_CODE_CERT_STORE is a partial exception: it has no dedicated schema key, so it goes in the env block or the process environment. If your config is drifting more broadly, /doctor inside Claude Code gives you an automated read on installation, settings and extensions before you go hunting manually.

When it isn't you

Occasionally the outage really is upstream. A connection error is safe to retry because the request never landed — nothing was charged and no state changed — so back off briefly before rewriting any network configuration.

Sometimes the honest answer is that Anthropic is having a bad hour. Check whether Claude is down before rewriting your network config. And unlike a 400, a genuine connection error is safe to retry — the request never landed, so nothing was double-charged and no state changed. Retry with a little backoff; if it clears within a minute or two, it was transient.

Don't confuse this with the error-code family, though. A 529 overloaded error means Anthropic's servers received you and were too busy, which is why it and the related overloaded error both deserve backoff rather than a proxy hunt. A stream that starts and then stalls mid-response is different again — see stream idle timeouts, governed by API_FORCE_IDLE_TIMEOUT, which overrides the 5-minute idle cutoff that aborts a streaming response when no bytes arrive.