Claude Code SSL Certificate Verification Failed: Fix It by Error Code

If Claude Code fails with API Error: Unable to connect to API: SSL certificate verification failed (UNABLE_TO_GET_ISSUER_CERT_LOCALLY) or Self-signed certificate detected (SELF_SIGNED_CERT_IN_CHAIN), the error's own advice is right: something between you and Anthropic — usually Zscaler, Netskope or another TLS-inspecting proxy — is re-signing your traffic with a corporate root certificate that Claude Code doesn't trust. The fix that works is the error's two suggestions applied in the opposite order:

1. Get your corporate root into the OS trust store (IT has often done this already).
2. Make sure your runtime can read that store. The native installer always can; an npm install needs Node 22.15 or later.
3. Only if it can't, set NODE_EXTRA_CA_CERTS to the root's .pem — and confirm it loaded in claude --debug, not /status.

If the code in brackets is CERT_NOT_YET_VALID or ERR_TLS_CERT_ALTNAME_INVALID instead, no certificate setting will help — read the code first.

If it says UNABLE_TO_GET_ISSUER_CERT (or _LOCALLY on an HTTP MCP server) and started right after updating to 2.1.304, your setup is probably fine — it's a regression.

Why that order? Most guides repeat only the first half of the message — set NODE_EXTRA_CA_CERTS. That works for some people and not others, and the inconsistency is the actual clue. Claude Code already trusts your operating system's certificate store by default. From the enterprise network docs:

Enterprise TLS-inspection proxies work without additional configuration when their root certificate is installed in the OS trust store and the runtime can read it.

So if your corporate CA certificate is already in the OS store and the SSL error persists, adding a .pem path is treating a symptom. Start with that second clause instead — and the runtime can read it.

UNABLE_TO_GET_ISSUER_CERT after updating to 2.1.304

Short answer: it's a regression. Pin 2.1.303 and turn off auto-updates until a fix ships (commands below).

Since 2.1.304, issue #103680 reports every request failing for Bedrock behind an HTTPS gateway signed by a private CA:

API Error: Unable to connect to API: SSL certificate verification failed (UNABLE_TO_GET_ISSUER_CERT). The certificate comes from an authority Claude Code doesn't trust, usually a TLS-inspecting corporate proxy or a gateway signed by a private CA: set NODE_EXTRA_CA_CERTS to that CA bundle, or add it to the system certificate store

A commenter sees the same on an HTTP MCP server ("type": "http") as UNABLE_TO_GET_ISSUER_CERT_LOCALLY: unable to get local issuer certificate.

It's this bug, not your proxy, when all three hold:

• the same setup worked on 2.1.303;
• your CA configuration hasn't changed;
• the claude --debug log shows CA certs: Loaded … system CA certificates or CA certs: Appended extra certificates from NODE_EXTRA_CA_CERTS, and the request still fails.

Your NODE_EXTRA_CA_CERTS and CLAUDE_CODE_CERT_STORE setup is still correct, so keep it. Per the issue, the CAs load but aren't used for the connection. Pin the last working version (other install methods):

claude install 2.1.303

Then stop the background updater from moving you forward again, in ~/.claude/settings.json:

{ "env": { "DISABLE_AUTOUPDATER": "1" } }

claude doctor should report auto-updates as disabled (set by env: DISABLE_AUTOUPDATER). Remove both once a fix ships.

Status (Oct 21, 2026): still broken in 2.1.306, confirmed by the issue author. The same error is reported in Claude Desktop's Code tab in 3P mode (Bedrock or a gateway) with a custom CA. No Desktop workaround is confirmed yet: claude install 2.1.303 only pins the terminal CLI, not the version bundled inside Desktop. Follow #103680 for the fix.

One comment thread links a failure to an emSign Root TLS CA - G1 CRL with an invalid signature (unconfirmed, possibly a separate cause).

The exact error messages this fixes

Claude Code prints the failure in two forms. On a request:

API Error: Unable to connect to API: SSL certificate verification failed (UNABLE_TO_GET_ISSUER_CERT_LOCALLY). The certificate comes from an authority Claude Code doesn't trust, usually a TLS-inspecting corporate proxy or a gateway signed by a private CA: set NODE_EXTRA_CA_CERTS to that CA bundle, or add it to the system certificate store · see https://code.claude.com/docs/en/network-config
 
API Error: Unable to connect to API: Self-signed certificate detected (SELF_SIGNED_CERT_IN_CHAIN). The certificate comes from an authority Claude Code doesn't trust, usually a TLS-inspecting corporate proxy or a gateway signed by a private CA: set NODE_EXTRA_CA_CERTS to that CA bundle, or add it to the system certificate store · see https://code.claude.com/docs/en/network-config

And during /login or the startup connectivity check:

OAuth error: SSL certificate error (CERT_NOT_YET_VALID). If you are behind a corporate proxy or TLS-intercepting firewall, set NODE_EXTRA_CA_CERTS to your CA bundle path, or ask IT to allowlist *.anthropic.com. Run `claude doctor` for details.
 
OAuth error: SSL certificate error (ERR_TLS_CERT_ALTNAME_INVALID). If you are behind a corporate proxy or TLS-intercepting firewall, set NODE_EXTRA_CA_CERTS to your CA bundle path, or ask IT to allowlist *.anthropic.com. Run `claude doctor` for details.

API Error: Unable to connect to API appears on requests; OAuth error appears at login. Same codes, same fixes.

Two version notes from the error reference. Before v2.1.273, the request-time messages ended at Check your proxy or corporate SSL certificates, with no code and no NODE_EXTRA_CA_CERTS hint — same causes, less information. And since v2.1.199, a certificate failure is reported on the first attempt instead of after the full retry budget; if yours took minutes to appear, you're on an older version.

If the error names a code, read the code first

Both forms suggest the same fix whatever the code says. The code is what tells you whether it can work. Node's error reference defines them:

ERR_TLS_CERT_ALTNAME_INVALID is not a trust problem. The certificate may be perfectly trusted — it's just for a different name. Behind a corporate network that commonly means something in the path answered on Anthropic's behalf with its own certificate: a block page, a captive login, or an interception rule that doesn't cover the API host properly. No CA bundle changes the name on a certificate. The fix sits with whoever runs the proxy: exempt the Anthropic hosts from inspection, or fix the rule.

CERT_NOT_YET_VALID is almost always your clock. The certificate's start date is in the future relative to your machine. VMs resumed from suspend, dual-boot systems and disabled time sync are the usual culprits. Sync the clock before touching any certificate setting.

Whatever the code, don't reach for NODE_TLS_REJECT_UNAUTHORIZED=0. The error reference calls it out by name: it disables certificate validation entirely.

The two "possibly" codes are where the confusion lives, and where the rest of this post applies.

UNABLE_TO_GET_ISSUER_CERT_LOCALLY ("SSL certificate verification failed")

OpenSSL's definition is that the issuer certificate of an untrusted certificate cannot be found. In plain terms: Claude Code followed the chain it was given up to an issuer it has no copy of — not in the bundled Mozilla set, not in the OS store it can read, not in NODE_EXTRA_CA_CERTS. Behind TLS inspection, that issuer is your proxy's root. The same applies to an LLM gateway behind ANTHROPIC_BASE_URL whose certificate comes from a private CA — the message names that case too.

SELF_SIGNED_CERT_IN_CHAIN ("Self-signed certificate detected")

Here the chain could be built, but it ends in a self-signed root that isn't in any trust store Claude Code uses. Node's error reference gives this code the same one-line description as the one above, and the fix is the same: get that root trusted. The difference is only that the self-signed root arrived as part of the chain the server sent. "Self-signed" here describes that root — root certificates sign themselves — not a misconfigured server. A server presenting a self-signed certificate of its own is a different code, DEPTH_ZERO_SELF_SIGNED_CERT.

Find which certificate your proxy is presenting

Before exporting anything, look at what you actually receive when you connect to Anthropic's API from the affected machine:

openssl s_client -connect api.anthropic.com:443 -servername api.anthropic.com -showcerts </dev/null

If your network only allows outbound traffic through an explicit proxy, add -proxy proxy.example.com:8080 and s_client tunnels through it with an HTTP CONNECT.

Read the Certificate chain block near the top. Each certificate has an s: line (subject) and an i: line (issuer). Behind TLS inspection, the issuers name your security vendor or your company's internal CA rather than a public certificate authority — that's the root you need trusted. Two caveats from the OpenSSL manual: -showcerts prints only what the server sent, in the order it sent it, and it is not a verified chain. And the Verify return code line at the end is OpenSSL's verdict against its own default trust store, which isn't necessarily the store Claude Code reads.

Once you have the root as a .pem, test it before pointing Claude Code at it:

openssl s_client -connect api.anthropic.com:443 -servername api.anthropic.com -CAfile /path/to/corp-ca.pem </dev/null

Verify return code: 0 (ok) means that file is the right root. Anything else, and setting NODE_EXTRA_CA_CERTS to it won't help either.

If you use Amazon Bedrock or Google Cloud's Agent Platform, model traffic goes to your provider rather than api.anthropic.com, so test against the endpoint your requests actually reach.

The one sentence that explains the inconsistency

Reading the OS store requires a runtime that exposes tls.getCACertificates:

On an older Node, only the bundled Mozilla set and NODE_EXTRA_CA_CERTS apply. That single line explains why the same fix works for your colleague and not for you: they're on the native installer, you're on an npm install with Node 20.

Check your runtime before changing any certificate setting:

node --version        # npm installs: needs >= 22.15 to read the OS store
claude doctor

If you're on an npm install with an older Node, you have two real options — upgrade Node, or keep using NODE_EXTRA_CA_CERTS, which genuinely is the right tool in that situation.

The variable that actually decides: CLAUDE_CODE_CERT_STORE

This one is barely mentioned anywhere, and it's the switch that controls the whole behaviour. It takes a comma-separated list of sources:

The default is bundled,system — both. To trust only one:

export CLAUDE_CODE_CERT_STORE=system     # OS store only
export CLAUDE_CODE_CERT_STORE=bundled    # bundled Mozilla set only

⚠️ It has no dedicated settings.json schema key. Set it in the env block of ~/.claude/settings.json or directly in the process environment. Putting it at the top level of a settings file does nothing, silently.

If your corporate CA is in the OS store and the SSL failure persists, check that nothing has narrowed this to bundled — that alone will reject every corporate certificate your proxy presents.

Verify the certificate loaded — /status will lie to you

This is the trap that turns a ten-minute certificate fix into an afternoon.

/status shows an Additional CA cert(s) row with your NODE_EXTRA_CA_CERTS path. It shows the path without checking the file loaded. A typo'd path, a permissions problem, a malformed PEM — all look identical to success.

Use the debug log instead:

claude --debug

Output goes to ~/.claude/debug/<session-id>.txt, not the terminal. Look for these:

CA certs: Appended extra certificates from NODE_EXTRA_CA_CERTS (/etc/ssl/certs/corp-ca.pem)
mTLS: Loaded client certificate from CLAUDE_CODE_CLIENT_CERT
mTLS: Loaded client key from CLAUDE_CODE_CLIENT_KEY

If a file couldn't be read, you get a Failed to read or Failed to load line with the reason. That's the difference between guessing and knowing.

The /status rows for mTLS client cert and mTLS client key are more honest — they appear only when the files loaded, so a missing row means the load failed.

Proxy configuration, and the parts that surprise people

export HTTPS_PROXY=https://proxy.example.com:8080
export NO_PROXY="localhost,192.168.1.1,.example.com"

Four things worth knowing:

• Precedence is fixed. Claude Code uses the first one set, in the order https_proxy, HTTPS_PROXY, http_proxy, HTTP_PROXY. Lowercase variants work. If you set two and get the wrong one, that's why.
• SOCKS proxies are not supported. At all.
• You don't need a loopback entry in NO_PROXY. WebSocket connections to localhost, ::1 and 127.0.0.0/8 never go through the proxy.
• The proxy URL is the one setting validated at startup. An unparseable value — one missing the http:// scheme, say — stops launch with an error naming the variable. Everything else on this page fails later, on a request.

And the timing rule underneath all of it: variables are read once at startup. A running session doesn't pick up changes to your shell environment, so export then retry in the same session proves nothing.

Certificates aren't the only thing an inspecting proxy or gateway can break. One that cuts streaming responses short or rewrites them also breaks auto mode's safety check, which shows up as auto mode's classifier giving no verdict — even on pwd.

Why your settings work in the terminal but not the Desktop Code tab

This one produces a genuinely confusing bug report, and it's deliberate behaviour rather than a fault.

When the Desktop app manages the provider connection, Claude Code reads NODE_EXTRA_CA_CERTS, the mTLS variables and HTTP_PROXY/HTTPS_PROXY/NO_PROXY only from managed settings and ~/.claude/settings.json. It ignores them in a repository's own settings files — so a checked-out repo can't redirect the TLS or proxy path of a session whose credentials come from the app.

That's a sensible security boundary: otherwise cloning a repository could reroute your authenticated traffic. But if you put your CA config in a project's .claude/settings.json, it will work in your terminal and silently not in the Desktop Code tab. Related: issue #22559.

A local, SSH or WSL Code tab session signed in through claude.ai isn't app-managed, so it reads every settings scope like a normal terminal session.

Cloud sessions ignore these entirely — the hosting environment owns the connection. NODE_EXTRA_CA_CERTS, NODE_TLS_REJECT_UNAUTHORIZED and the client-certificate variables are all dropped, and each ignored key is noted in the session's debug log.

Background agents don't inherit your shell

If you use claude agents, --bg or /background, this will bite you eventually.

Background sessions run under a per-user supervisor process that outlives your shell. It inherits the environment of whichever shell started it first — and an OS-installed supervisor gets no shell environment at all.

So exporting your proxy or CA variables in .bashrc reaches background agents when that shell happened to cold-start the supervisor, and silently doesn't when a different one did. Same machine, same config, non-deterministic result.

Put them in the env block of ~/.claude/settings.json instead. Settings are the only configuration that reaches every background session:

{
  "env": {
    "HTTPS_PROXY": "https://proxy.example.com:8080",
    "NODE_EXTRA_CA_CERTS": "/etc/ssl/certs/corp-ca.pem",
    "CLAUDE_CODE_CERT_STORE": "bundled,system"
  }
}

An already-running supervisor keeps the configuration it started with, so run claude daemon stop --any after changing this.

Client certificates, if your gateway requires them

export CLAUDE_CODE_CLIENT_CERT=/path/to/client-cert.pem
export CLAUDE_CODE_CLIENT_KEY=/path/to/client-key.pem
export CLAUDE_CODE_CLIENT_KEY_PASSPHRASE="your-passphrase"

Rotation is handled better than most people expect: replace the files at the same paths and a running session picks them up. Since v2.1.232, a connection-level failure — a reset or a TLS handshake error — triggers a re-read and a retry with the new pair.

Two caveats. Claude Code re-reads in response to failures, not by watching files, so nothing happens at the moment you swap them. And if the gateway completes the handshake and returns an HTTP error instead of resetting, there's no re-read — you wait for the next settings apply or a restart.

Triage order

1. Read the code in brackets. CERT_NOT_YET_VALID, CERT_HAS_EXPIRED or ERR_TLS_CERT_ALTNAME_INVALID mean a clock or proxy-rule problem, not a missing CA.
2. Is your corporate root in the OS trust store? openssl s_client … -showcerts tells you which root the proxy is presenting. If it's installed, this should already work — go to step 3 rather than adding a .pem.
3. Can your runtime read the OS store? Native installer, or npm on Node ≥ 22.15. If not, that's your SSL error explained.
4. Check nothing narrowed CLAUDE_CODE_CERT_STORE away from bundled,system.
5. Set NODE_EXTRA_CA_CERTS only if 3 rules out the OS store — test the file with openssl s_client -CAfile first, then confirm in the debug log, not /status.
6. If it works in the terminal but not the Desktop Code tab, move the config to ~/.claude/settings.json.
7. If it works interactively but not for background agents, move it to the env block and claude daemon stop --any.

The reason the Claude Code SSL certificate error burns so much time in enterprises isn't that it's hard — it's that the default behaviour is better than people expect, so everyone reaches for the override first and then debugs the override. Establish whether the OS store is being read at all, and most of these tickets close in ten minutes.

Related errors

For anything not in this table, the full list of Claude Code errors and fixes covers every error I've written up, grouped by cause.