unable to get local issuer certificate — the error that fails on the first try and never retries

Almost everything that can go wrong between your client and an endpoint is retried for you — server errors, overload, request timeouts, dropped connections and temporary throttles all get up to 10 attempts with exponential backoff before anything reaches your screen. TLS certificate validation failure is one of the few that gets none. It is reported on the first attempt. That inverts how you should read it: an error that appears instantly and every time is not evidence the service is unstable — it is evidence the failure is local, deterministic, and yours to fix.

What you're seeing

Error: unable to get local issuer certificate

Error: self-signed certificate in certificate chain

{ code: 'SELF_SIGNED_CERT_IN_CHAIN' }
{ code: 'UNABLE_TO_VERIFY_LEAF_SIGNATURE' }

SSL certificate verification failed
SSL certificate error (...)

These are the same event described at four different heights. Your runtime took the certificate the server presented, tried to build a chain up to a root it already trusts, and couldn't finish. The message names where the walk stopped.

None of these means the server is down. A server that is down does not get far enough to present a certificate.

The asymmetry that makes this error look worse than it is

Read the table as a filter on what reaches your eyes. Anything with a retry budget has to fail ten times in a row, with growing gaps between attempts, before it surfaces. Anything with no budget surfaces on attempt one. So the errors that arrive fastest are systematically the ones nobody retries — which means a large share of failures people describe as "this service is flaky" are the opposite: a stable, local, reproducible misconfiguration that simply had nothing standing between it and the terminal.

The practical version: an error that takes 30 seconds to appear and an error that appears instantly are not the same class of problem, even when the text looks similar. Time-to-error is diagnostic information. Use it before you change anything.

Two honest caveats. Certificate failures were not always exempt from retries — older client versions ran them through the full budget first, so on an older build a certificate problem does look slow and flaky. And "TLS error" is not the same as "certificate error": a handshake that times out is transient and still retried. Confirm the behaviour on the client version you're actually running before relying on timing as a signal.

Which layer is actually broken

Most write-ups on this error jump straight to "add the certificate." That works for rows two and three and does nothing at all for rows one, four, and five. The next section is ordered so you find out which row you're in before you edit anything.

Check in this order

HOST=api.9coding.com
openssl s_client -connect "$HOST:443" -showcerts </dev/null 2>/dev/null \
  | openssl x509 -noout -issuer -subject -dates

node -p "process.version"
node -p "typeof require('tls').getCACertificates"   # "function" = can read the OS store

security find-certificate -a -p /Library/Keychains/System.keychain > ~/corp-ca.pem
security find-certificate -a -p /System/Library/Keychains/SystemRootCertificates.keychain >> ~/corp-ca.pem

Get-ChildItem Cert:\LocalMachine\Root, Cert:\LocalMachine\CA |
  ForEach-Object {
    "-----BEGIN CERTIFICATE-----"
    [Convert]::ToBase64String($_.RawData, 'InsertLineBreaks')
    "-----END CERTIFICATE-----"
  } | Set-Content -Encoding ascii $HOME\corp-ca.pem

sudo cp corp-root.crt /usr/local/share/ca-certificates/corp-root.crt   # Debian/Ubuntu
sudo update-ca-certificates
# RHEL/Fedora: /etc/pki/ca-trust/source/anchors/ then `sudo update-ca-trust`

export NODE_EXTRA_CA_CERTS=/etc/ssl/certs/ca-certificates.crt   # Debian/Ubuntu
# macOS/Windows: the file you just wrote

openssl s_client -connect "$HOST:443" -CAfile "$NODE_EXTRA_CA_CERTS" </dev/null 2>&1 \
  | grep -i 'verify return code'
# want: Verify return code: 0 (ok)

claude --debug
# then read the newest file under ~/.claude/debug/

# <model-id>: copy an id from https://api.9coding.com/v1/models
curl -sS -w '\n%{http_code}\n' https://api.9coding.com/v1/messages \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "content-type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{"model":"<model-id>","max_tokens":16,"messages":[{"role":"user","content":"hi"}]}'

node -e 'require("https").get("https://api.9coding.com/", r => console.log(r.statusCode))
  .on("error", e => console.error(e.code, "-", e.message))'

The variable you'll be tempted to set, and shouldn't

Every thread about this error eventually surfaces NODE_TLS_REJECT_UNAUTHORIZED=0. It will make the error go away. Here is what it actually does.

It disables TLS certificate verification for the entire process — not for one host, not for one request. Every outbound HTTPS connection that process makes, including ones you didn't think about, will now accept any certificate from anyone able to sit between you and the destination. On a machine where traffic is already being intercepted, that is precisely the property you were relying on to notice.

You had a configuration problem, solvable in step 3 in about two minutes. This trades it for a security problem that is silent, permanent until someone notices, and travels with any script or image you copy the setting into. If you set it once during a five-minute experiment, unset it in the same session.

There is no version of this that is fine "just for testing on an internal endpoint." Trusting a specific CA is the same amount of work and leaves verification switched on for everything else.

When it isn't your problem

You are looking at the operator's certificate, not your setup, when:

• step 1 shows an issuer that is a public CA, and notAfter has passed,
• or step 1 shows a leaf with no intermediates and curl fails the same way,
• and the same failure reproduces from a different machine on a different network — a phone hotspot is enough,
• and it started without any change on your side.

Certificate expiry is a scheduled event that someone missed, so it usually resolves in hours rather than minutes. Check the operator's status page before you spend the afternoon regenerating trust stores — ours is at status.

When reporting it, include the request id — 9Coding error responses carry one in the form (request id: 2026...). That id plus the timestamp, the model name and the full error text lets the exact call be traced. A report that only says it doesn't work cannot be investigated.

Certificate errors and connection errors are not the same problem

A certificate error means the connection succeeded and then verification failed — you got far enough to be handed a certificate. ECONNREFUSED, ETIMEDOUT, and fetch failed mean you never got there, and no amount of CA configuration will change them. They also retry, which is why they feel slow and this one feels instant. See connection errors.

Related

• Connection errors — separating network, proxy, and endpoint
• 401 Unauthorized — two layers of authentication, one error message
• 429 Too Many Requests — why the retries are already gone by the time you see it
• All Claude Code errors — the quick reference table