Omniscio

OmniscioGuidesThe proxy refused the tunnel

Claude Code: the proxy refused the tunnel (ERR_PROXY_TUNNEL)

Last checked against Anthropic's documentation on November 17, 2026. By the Omniscio team. Updated .

What is the exact message?

Couldn't connect through your proxy (ERR_PROXY_TUNNEL) — the proxy refused the tunnel: check its credentials and that it allows this host

Anthropic's error reference carries the wording under its connection errors, beside the other ways a request fails before it reaches the API.

What is it actually saying?

Claude Code does not connect to the API directly when a proxy is configured. It asks the proxy to open a tunnel to the host, and the proxy answers.

Here the answer was a refusal. So the failure is between your machine and the proxy, or at the proxy itself: nothing of yours reached the API.

That is why the message names two suspects rather than a cause. The proxy either wanted a credential it did not get, or it does not permit that host.

The causes, most likely first

  • The proxy wants credentials. Anthropic says to put basic-authentication credentials in the proxy URL itself, and warns against hardcoding a password in a script.
  • The proxy does not allow this host. Anthropic publishes the hosts Claude Code needs. A proxy that never had api.anthropic.com on its list refuses the tunnel however good your credentials are.
  • The proxy address is wrong or unreachable. Claude Code reads the proxy variables once at startup, so a value from another network follows you into a session.
  • The proxy failed on its own side. It could not open the tunnel for a reason in its own logs, which is your proxy administrator's to read. This message does not print that reason.

How do I fix it?

  1. Test the proxy on its own. Run curl -x http://proxy.example.com:8080 -I https://api.anthropic.com with your own proxy address, from the shell you start Claude Code in. On Windows PowerShell run curl.exe.
  2. Add credentials. If the test asks for authentication, put them in the proxy URL itself, for example http://user:pass@proxy.example.com:8080, and set that whole URL as HTTPS_PROXY from your shell or vault rather than typing a password into a script.
  3. Ask for the host. If credentials do not help, the allowlist is the answer. Anthropic's network page lists the hosts a normal install needs, starting with api.anthropic.com, claude.ai and platform.claude.com.
  4. Then restart Claude Code. Proxy variables are read once at startup, so a new value only applies to a new session.

Keep any NO_PROXY entry narrow. A broad entry bypasses the proxy for other hosts your organization expects to stay on it, and Anthropic warns about exactly that.

How do I know it is fixed?

  • The curl -x test returns a status line such as HTTP/2 200 instead of a refusal.
  • Claude Code gets a normal answer on its next request, with no proxy line in the reply.

If the check passes and Claude Code still fails, the two are not talking to the same proxy. A shell export reaches Claude Code only when it was started from that shell.

Where these answers come from

Common questions

Which variable sets the proxy?

HTTPS_PROXY is the usual one, and HTTP_PROXY sits beside it. Lowercase spellings work too, and Claude Code uses the first one set in the order https_proxy, HTTPS_PROXY, http_proxy, HTTP_PROXY.

Should I put the proxy in my shell or in settings?

Settings, if background agents must use it. A shell export reaches background agents only when that same shell happened to start the shared supervisor, so Anthropic suggests the env block of ~/.claude/settings.json instead.

Does the message tell me which of the two it is?

No. This one is a single sentence with no status code in it, so the curl check is how you find out: an authentication demand points at credentials, and a refusal of the host points at the allowlist.