self-signed certificate in certificate chain: the root CA is unknown to the client

What error does an unknown root CA cause?

A service with a certificate from an internal or private CA is reachable, but a client aborts the check. The wording depends on whether the server also sends the root.

Does the server send the root?

openssl s_client:  Verify return code: 19 (self-signed certificate in certificate chain)
Node:              SELF_SIGNED_CERT_IN_CHAIN - self-signed certificate in certificate chain
curl (macOS):      curl: (60) SSL certificate problem: self signed certificate in certificate chain
Python (LibreSSL): [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self signed certificate in certificate chain

LibreSSL (curl and system Python on macOS) and OpenSSL up to 1.1.1 write self signed without a hyphen, OpenSSL 3.0 and later with.

And if it does not send the root?

That is the normal case:

openssl s_client:  Verify return code: 20 (unable to get local issuer certificate)
Node:              UNABLE_TO_GET_ISSUER_CERT_LOCALLY - unable to get local issuer certificate
curl:              curl: (60) SSL certificate problem: unable to get local issuer certificate
Python:            [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate

What do browsers and Java report?

Chromium and Firefox report this in both cases (measured with Chromium 151 and Firefox 153):

Chromium:          net::ERR_CERT_AUTHORITY_INVALID
Firefox:           SEC_ERROR_UNKNOWN_ISSUER

Java reports this in both cases too (OpenJDK source code):

PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

Is only the root missing?

That assumes the server sends all intermediates. If an intermediate certificate is missing instead, when nginx sends an incomplete certificate chain helps; the section “How do I find out whether only the root is missing?” tells the two cases apart.

Does it help to send the root from the server?

Anyone who reads unable to get local issuer certificate concludes the chain is broken and appends the root to the file the server delivers. That changes the message, not the result. Measured with a throwaway CA: the same chain fails with error 20 without the root and with error 19 with it appended.

Measurement and edge cases: error number per client

Measured against openssl, curl, Python and Node. openssl gives the number, Python only in the exception’s verify_code (the message lacks it), curl and Node the matching text.

Why does the client not know the root?

A client checks whether a chain of signatures leads from the server certificate to a certificate it trusts, the trust anchor. The server supplies leaf and intermediates but cannot supply the anchor: a self-signed certificate only vouches for itself, and the client decides whether to trust it. The roots of public CAs are preinstalled, the root of your own CA is not.

Which store does which client read?

  • Java reads the cacerts file of the installation.
  • Node uses the bundled Mozilla set or OpenSSL’s default store, depending on the build (Node documentation: chosen at build time); node --help marks it (default).
  • Python requests uses the certifi package, not the system store (requests documentation).
Measurement and edge cases: Node builds

Measured: official binary v26.9.0 --use-bundled-ca, Homebrew --use-openssl-ca.

How do I find out whether only the root is missing?

The chain the server sends can be queried without a browser:

openssl s_client -showcerts -connect server.example.internal:443 -servername server.example.internal </dev/null

Certificate chain lists each certificate sent with subject (s:) and issuer (i:), then comes Verify return code. Read it like this:

  • 19, the last entry has the same s: and i:: the server sends the root, the client does not know it.
  • 20 with at least two entries: the issuer of the last entry is missing on the client, i: there names it. Either it is the root or a further intermediate the server does not send (then when nginx sends an incomplete certificate chain helps); the control test tells them apart.
  • 21 (unable to verify the first certificate) with exactly one entry: only the leaf arrives. Either an intermediate is missing, or the root signed the leaf directly (single-tier PKI). Both end at 21; the control test tells them apart.

What does the control test look like?

For the control test, the root is obtained as a file and saved as root.pem. The CA operator supplies it in PEM format (text starting with -----BEGIN CERTIFICATE-----). The control test gives the client only this file:

openssl s_client -connect server.example.internal:443 -servername server.example.internal -CAfile root.pem </dev/null 2>&1 | grep 'Verify return code'

root.pem contains only the root being checked, and -CApath stays out.

Measurement and edge cases: why no -CApath

A missing intermediate in a directory given in addition silently fills the gap, and the control test reports 0 (ok) although the server sends an incomplete chain (measured with OpenSSL 3.6.4). With -CAfile alone, openssl draws on no further directory.

With Verify return code: 0 (ok) the server carries the chain correctly and only the client’s trust is missing. If the code stays at 20 or 21, an intermediate is still missing on the server (see when nginx sends an incomplete certificate chain), or root.pem is not the root of this chain.

How do I fix it?

First: How do I verify the root?

A trust anchor (here the file root.pem from the control test) is only added after verification, because it applies to everything the CA signs; compare the fingerprint with the operator’s value over a second channel:

openssl x509 -in root.pem -noout -subject -fingerprint -sha256

Second: Where do I put the root?

The root goes where the failing client looks. In the system store on Debian and Ubuntu (the .crt extension is required):

sudo cp root.pem /usr/local/share/ca-certificates/company-root.crt
sudo update-ca-certificates

On RHEL and relatives:

sudo cp root.pem /etc/pki/ca-trust/source/anchors/company-root.pem
sudo update-ca-trust extract

On macOS:

sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain root.pem

How does that work on Windows?

root.cer is the root in binary DER form, whose text form is root.pem. Microsoft’s documentation does not say which encoding certutil -addstore accepts (as of 1 May 2025), and it is not measured here; DER is the choice without a text wrapper.

Convert it beforehand with openssl on the machine where the root was verified. The fingerprint must match the one from the first step:

openssl x509 -in root.pem -outform DER -out root.cer
openssl x509 -inform DER -in root.cer -noout -fingerprint -sha256

Then copy root.cer to the Windows machine and run there as administrator:

certutil -addstore -f Root root.cer

And for curl, Node and Python?

Not every client reads the system store (for requests, Java and Node see “Which store does which client read?”). curl and Python ssl read their TLS library’s default store, for Python with OpenSSL on macOS the file /private/etc/ssl/cert.pem (measured: 128 certificates; whether the macOS step above changes it is not measured). These clients get the root individually:

curl --cacert root.pem https://server.example.internal/
CURL_CA_BUNDLE=/path/root.pem curl https://server.example.internal/
NODE_EXTRA_CA_CERTS=/path/root.pem node app.js

Python (requests alternatively via REQUESTS_CA_BUNDLE):

ctx = ssl.create_default_context(cafile="/path/root.pem")
requests.get(url, verify="/path/root.pem")

--cacert, cafile and verify= replace the default store, NODE_EXTRA_CA_CERTS adds to it (curl and Node docs).

Measurement and edge cases: effect of the root on the clients

Measured: with the root, all errors disappear (HTTP 200).

After cafile=root.pem, a public site fails with error 20 in Python with OpenSSL, with NODE_EXTRA_CA_CERTS it answers.

System curl (SecureTransport) and system Python on macOS accept it even with only the throwaway root.

And for Java?

Java needs a truststore that contains the root:

keytool -importcert -alias company-root -file root.pem -keystore truststore.p12 -storetype PKCS12
java -Djavax.net.ssl.trustStore=truststore.p12 -Djavax.net.ssl.trustStorePassword=... -jar app.jar

The property javax.net.ssl.trustStore replaces the default truststore (JSSE reference), so public CAs must be in that file too. Alternatively, keytool -importcert -cacerts ... adds it to the installation’s cacerts.

Third: May I switch the check off?

No. curl -k, verify=False and NODE_TLS_REJECT_UNAUTHORIZED=0 make the error disappear because they disable the check, leaving the connection open to any man in the middle. Sending the root from the server does not help (see above).

When does the PKI Toolkit help?

If it is unclear which file of a CA bundle is the root, our PKI Toolkit helps. The tool:

  • reads the files in the browser without upload,
  • checks the signature of each entry against its issuer for RSA (PKCS#1 and PSS) and ECDSA (P-256, P-384, P-521), for Ed25519 only if the browser supports it, and reports other algorithms as not checked,
  • labels the self-signed certificate at the chain end as “self-signed (root)”,
  • outputs fullchain.pem with or without the root.

It does not know which roots a client has; only the command from “How do I find out whether only the root is missing?” shows whether the root is missing there.

Let's talk

Free initial consultation - no sales pitch, just an honest assessment.

Request a consultation →