If a script, a package install or a git clone just stopped with certificate verify failed or unable to get local issuer certificate, this page helps you find and fix the cause. Your tool could not link the server’s certificate to a certificate authority (CA, an organization whose root certificate your system already trusts). Usually one piece is missing: the server forgot its intermediate certificate, or your machine lacks the root of a company proxy or internal CA. One openssl command tells you which, so you repair the server’s chain or add the root to the trust store your tool reads.
What you’ll accomplish
- Read the
Verify return codefromopenssl s_clientand know which cause you are facing. - Fix an incomplete chain on the server, so every client benefits at once.
- Add a missing root to the right trust store for Python, Node, Git, curl, Java, R or PowerShell.
- Confirm the repair from more than one client, with verification still on.
Prerequisites
openssl1.1.1 or newer on the failing machine. Thex509 -extflag used below does not exist in 1.0.2. Sample output is from OpenSSL 3.5. Versions 1.1.1 and 3.0 put spaces around each=.- A shell, with
sudo, on the client that shows the error. Your laptop may not sit behind the same proxy as a failing build agent. - Your distribution family, because each one installs roots differently (step 7). Alpine needs the
ca-certificatespackage first. - If the client runs in a container, run every command inside it. A container carries its own frozen trust store, so fixing the host changes nothing there.
How it works
Verifying a certificate means building a path. The server sends its own certificate (the leaf) plus any intermediate CA certificates that link it to a root. The client reads the leaf’s Issuer, finds a certificate whose Subject matches, and repeats. The walk ends at a root already in the client’s trust store, called the trust anchor. If the client runs out of certificates first, verification fails.
The trust anchor is never sent, because a client will not start trusting a root because a server offered it. The intermediates, however, must be sent. The client has no other reliable way to get them, and they are what goes missing when a web server points at cert.pem instead of fullchain.pem.
Since May 2026, Let’s Encrypt issues from its YR1 and YR2 intermediates by default. Their chain includes Root YR, cross-signed by ISRG Root X1 (signed a second time, so existing trust stores accept it). Older guides showing R10 or R11 describe the same shape with one link fewer.
OpenSSL names the broken link with a numbered verify code, and each number points to a different fix.
Step-by-step
1. Reproduce at the TLS layer. Ask OpenSSL directly, since application errors hide detail. Always pass -servername. It sets SNI (Server Name Indication, the hostname the client announces at the start of the connection). Without it, a server hosting several sites may hand you the wrong certificate.
openssl s_client -connect app.example.com:443 -servername app.example.com </dev/null 2>&1 | grep 'Verify return code'
Example output:
Verify return code: 21 (unable to verify the first certificate)
If nothing prints, the connection itself failed. Run the command without the grep to read the network error, such as a timeout or a refused connection.
2. Read the chain the server actually sent. The Certificate chain block shows how many certificates arrived and how they link.
openssl s_client -connect app.example.com:443 -servername app.example.com </dev/null 2>/dev/null \
| sed -n '/Certificate chain/,/^---/p'
A broken, leaf-only chain stops at depth 0:
Certificate chain
0 s:CN=app.example.com
i:C=US, O=Let's Encrypt, CN=YR1
a:PKEY: RSA, 2048 (bit); sigalg: sha256WithRSAEncryption
v:NotBefore: Sep 14 03:12:09 2026 GMT; NotAfter: Dec 13 03:12:08 2026 GMT
---
A correct chain continues, and each i: (issuer) matches the s: (subject) on the next entry:
Certificate chain
0 s:CN=app.example.com
i:C=US, O=Let's Encrypt, CN=YR1
a:PKEY: RSA, 2048 (bit); sigalg: sha256WithRSAEncryption
v:NotBefore: Sep 14 03:12:09 2026 GMT; NotAfter: Dec 13 03:12:08 2026 GMT
1 s:C=US, O=Let's Encrypt, CN=YR1
i:C=US, O=ISRG, CN=Root YR
a:PKEY: RSA, 2048 (bit); sigalg: sha256WithRSAEncryption
v:NotBefore: Sep 3 00:00:00 2025 GMT; NotAfter: Sep 2 23:59:59 2028 GMT
2 s:C=US, O=ISRG, CN=Root YR
i:C=US, O=Internet Security Research Group, CN=ISRG Root X1
a:PKEY: RSA, 4096 (bit); sigalg: sha256WithRSAEncryption
v:NotBefore: May 13 00:00:00 2026 GMT; NotAfter: Sep 2 23:59:59 2032 GMT
---
The verify codes you will realistically see (OpenSSL 1.1.1 writes self signed without the hyphen):
- 0 (ok). The chain verified. If your tool still fails, it is not reading the store you think it is. Go to step 8.
- 10 (certificate has expired). Something in the path is past its end date, or your clock says so. Step 3.
- 18 (self-signed certificate). The leaf signed itself, which is normal only for one you made.
- 19 (self-signed certificate in certificate chain). The chain ends at a root you do not trust, often a TLS-inspecting proxy. Step 4.
- 20 (unable to get local issuer certificate). An issuer in the path is not in your trust store. Steps 4 and 7.
- 21 (unable to verify the first certificate). The leaf’s issuer was neither sent nor found locally. Usually an incomplete chain (step 6). Check step 4 first, since a proxy that sends only its leaf also gives 21.
3. Rule out expiry and clock skew. Split the served chain into files and print each certificate’s dates and names.
openssl s_client -connect app.example.com:443 -servername app.example.com -showcerts </dev/null 2>/dev/null \
| awk '/BEGIN CERTIFICATE/{n++; f=1} f{print > ("cert-" n ".pem")} /END CERTIFICATE/{f=0; close("cert-" n ".pem")}'
for f in cert-*.pem; do echo "== $f"; openssl x509 -in "$f" -noout -subject -issuer -enddate; done
Example output:
== cert-1.pem
subject=CN=app.example.com
issuer=C=US, O=Let's Encrypt, CN=YR1
notAfter=Dec 13 03:12:08 2026 GMT
== cert-2.pem
subject=C=US, O=Let's Encrypt, CN=YR1
issuer=C=US, O=ISRG, CN=Root YR
notAfter=Sep 2 23:59:59 2028 GMT
== cert-3.pem
subject=C=US, O=ISRG, CN=Root YR
issuer=C=US, O=Internet Security Research Group, CN=ISRG Root X1
notAfter=Sep 2 23:59:59 2032 GMT
Compare each notAfter date with today. Only cert-1.pem appears if the server sends the leaf alone.
An expired intermediate is easy to miss because the leaf looks fine. Then check the client’s clock, since a machine running days behind rejects valid certificates.
timedatectl status
Example output:
Local time: Fri 2026-10-02 10:37:18 UTC
Universal time: Fri 2026-10-02 10:37:18 UTC
RTC time: Fri 2026-10-02 10:37:18
Time zone: Etc/UTC (UTC, +0000)
System clock synchronized: yes
NTP service: active
RTC in local TZ: no
If System clock synchronized says no, fix time sync (NTP, the protocol that keeps clocks correct) before anything else.
4. Look at who issued the leaf. If the issuer is your employer or a firewall vendor rather than a public CA, traffic is being decrypted and re-signed on the way. A public CA such as DigiCert or Let's Encrypt means no proxy.
openssl s_client -connect api.stripe.com:443 -servername api.stripe.com </dev/null 2>/dev/null \
| openssl x509 -noout -issuer -subject
Example output:
issuer=C=CA, O=Contoso, CN=Contoso TLS Inspection CA
subject=CN=api.stripe.com
That is your company network doing its job. Trust its root (step 7) rather than bypassing it.
5. Confirm the name matches. A hostname mismatch also surfaces as CERTIFICATE_VERIFY_FAILED. Modern clients ignore the Common Name and read only the SAN (Subject Alternative Name, the list of names the certificate covers).
openssl s_client -connect app.example.com:443 -servername app.example.com </dev/null 2>/dev/null \
| openssl x509 -noout -ext subjectAltName
Example output:
X509v3 Subject Alternative Name:
DNS:app.example.com, DNS:www.app.example.com
If your hostname is missing from that list, the certificate must be reissued. No trust store change will help.
6. Fix an incomplete chain on the server. For code 21, fix the server once instead of every client. Web servers want the full chain in one file, leaf first.
ssl_certificate /etc/letsencrypt/live/app.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/app.example.com/privkey.pem;
sudo nginx -t && sudo systemctl reload nginx
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful
Any other message names the file and line to fix, and nginx keeps serving the old configuration until the test passes.
Apache 2.4.8 and later expect the intermediate inside SSLCertificateFile. Older releases use SSLCertificateChainFile. Run step 2 again. The chain block should now list entries beyond depth 0, and step 1 should print code 0.
7. Install a missing root in the system trust store. This fixes codes 19 and 20 for a CA you should trust, such as a company inspection root or an internal CA. Get the root as a PEM file (the text format that starts with -----BEGIN CERTIFICATE-----) from whoever runs it. Never copy it out of the failing handshake you are trying to verify.
On Debian and Ubuntu, the file must end in .crt and contain PEM text, or it is silently ignored:
sudo cp contoso-root.crt /usr/local/share/ca-certificates/contoso-root.crt
sudo update-ca-certificates
Updating certificates in /etc/ssl/certs...
1 added, 0 removed; done.
Running hooks in /etc/ca-certificates/update.d...
done.
On RHEL, Alma, Rocky and Fedora:
sudo cp contoso-root.crt /etc/pki/ca-trust/source/anchors/
sudo update-ca-trust extract
This prints nothing on success. On either family, run step 1 again. It should now end in code 0:
openssl s_client -connect app.example.com:443 -servername app.example.com </dev/null 2>&1 | grep 'Verify return code'
Verify return code: 0 (ok)
A code 20 here means the file you installed is not the root that signed this chain. Compare its subject with the last issuer from step 3.
On macOS, add the root to the System keychain from Terminal:
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain contoso-root.crt
It prints nothing on success. Many command-line tools read /etc/ssl/cert.pem instead of the Keychain, so also build a combined file for step 8:
cat /etc/ssl/cert.pem contoso-root.crt > ~/ca-bundle.pem
grep -c 'BEGIN CERTIFICATE' ~/ca-bundle.pem
Example output:
151
The count should be one higher than the same grep on /etc/ssl/cert.pem.
8. Make the failing tool read that store. If openssl now returns code 0 but your tool still fails, the tool keeps its own list. Find it below.
Point every file-path setting at a full bundle, not at your single root. Most of them replace the default list, so a root-only file breaks every public site. After step 7, the system bundle holds the public roots plus yours. It lives at /etc/ssl/certs/ca-certificates.crt on Debian and Ubuntu, and at /etc/pki/tls/certs/ca-bundle.crt on RHEL-family systems. On macOS, use the ~/ca-bundle.pem file you built above.
Python (requests, pip, urllib). The standard library reads OpenSSL’s default paths, but requests uses its own copy of the Mozilla roots, shipped in the certifi package. Check which files each one reads:
python3 -c "import ssl; print(ssl.get_default_verify_paths().openssl_cafile)"
python3 -c "import certifi; print(certifi.where())"
Example output:
/usr/lib/ssl/cert.pem
/home/dev/.venv/lib/python3.12/site-packages/certifi/cacert.pem
Point both at the system bundle and test. The same error again means the bundle still lacks your root (step 7):
export SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt
export REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt
python3 -c "import requests; print(requests.get('https://pypi.org/simple/', timeout=10).status_code)"
200
Since version 24.2, on Python 3.10 or newer, pip checks the operating system’s certificates in addition to certifi. Upgrading pip often fixes it on its own. On older versions, or to force a bundle, set it once:
pip config set global.cert /etc/ssl/certs/ca-certificates.crt
Writing to /home/dev/.config/pip/pip.conf
Python from python.org on macOS ignores the Keychain and ships with no roots. Run Install Certificates.command in /Applications/Python 3.x/, which installs certifi and ends with -- update complete. That covers public sites. For a company root, also point SSL_CERT_FILE and REQUESTS_CA_BUNDLE at ~/ca-bundle.pem.
Node, npm and webpack. Node carries its own built-in root list and ignores the system store by default. NODE_EXTRA_CA_CERTS adds your root to that list, so here the single root file is correct. Node reads it only at startup:
export NODE_EXTRA_CA_CERTS=/usr/local/share/ca-certificates/contoso-root.crt
node -e "require('https').get('https://registry.npmjs.org/', r => console.log(r.statusCode))"
200
Build tools such as webpack and Vite run inside Node and pick this up. For npm itself, set the bundle and read it back:
npm config set cafile /etc/ssl/certs/ca-certificates.crt
npm config get cafile
/etc/ssl/certs/ca-certificates.crt
On Node 22.15 or a newer release, node --use-system-ca reads the operating system store as well.
Git. On Linux, Git uses the system bundle unless someone overrode it. Set it explicitly, then test against any remote:
git config --global http.sslCAInfo /etc/ssl/certs/ca-certificates.crt
git ls-remote https://github.com/git/git.git HEAD
Example output:
4fd2bd7c6e2b0a8f3d1a96c5e0b7d2f81a3c9e44 HEAD
On Windows, company roots usually land in the Windows certificate store. Tell Git for Windows to read that store:
git config --global http.sslBackend schannel
There is no output. Run the git ls-remote test again to confirm.
curl. Pass a bundle per command with --cacert, or for every call with the CURL_CA_BUNDLE variable:
curl --cacert /etc/ssl/certs/ca-certificates.crt -sS -o /dev/null -w '%{http_code}\n' https://app.example.com/
200
Java. Java reports PKIX path building failed. PKIX is the standard Java uses to build a chain of trust. Java keeps roots in a keystore file, so copy the JDK’s default one and add your root to the copy. On Java 8 the file is $JAVA_HOME/jre/lib/security/cacerts. The default password is changeit:
sudo mkdir -p /opt/app
sudo cp "$JAVA_HOME/lib/security/cacerts" /opt/app/app-cacerts
sudo keytool -importcert -trustcacerts -noprompt -alias contoso-root \
-file /usr/local/share/ca-certificates/contoso-root.crt \
-keystore /opt/app/app-cacerts -storepass changeit
Certificate was added to keystore
Certificate not imported, alias <contoso-root> already exists means the root is already in the file. Start the app with that keystore, which survives JDK upgrades that overwrite cacerts:
java -Djavax.net.ssl.trustStore=/opt/app/app-cacerts \
-Djavax.net.ssl.trustStorePassword=changeit -jar app.jar
R (install.packages failing). R downloads packages with libcurl, the library behind curl. Check which TLS library it uses:
attr(libcurlVersion(), "ssl_version")
Example output:
[1] "OpenSSL/3.0.13"
On Linux, R uses the operating system’s CA certificates, so step 7 is the whole fix. On Windows, R 4.2 and later use Schannel, Microsoft’s TLS library, and the output names it. R then reads the Windows certificate store, so install the root there (see PowerShell). Older Windows builds without Schannel need CURL_CA_BUNDLE in ~/.Renviron instead.
Some company proxies also block Windows’ revocation check. R_LIBCURL_SSL_REVOKE_BEST_EFFORT=TRUE lets downloads continue when that check cannot finish, which R’s documentation says lowers security. To test:
print(download.file("https://cloud.r-project.org/", tempfile(), quiet = TRUE))
[1] 0
PowerShell. Invoke-WebRequest on Windows trusts the Windows certificate store. Windows PowerShell 5.1 reports Could not establish trust relationship for the SSL/TLS secure channel, and PowerShell 7 reports The SSL connection could not be established. Import the root from an elevated PowerShell window:
Import-Certificate -FilePath C:\certs\contoso-root.cer -CertStoreLocation Cert:\LocalMachine\Root
(Invoke-WebRequest https://app.example.com/ -UseBasicParsing).StatusCode
Example output:
PSParentPath: Microsoft.PowerShell.Security\Certificate::LocalMachine\Root
Thumbprint Subject
---------- -------
9C2B6E1F04A7D3B85E0C6A91F2D47B03E8A5C6D1 CN=Contoso TLS Inspection CA
200
Flags such as curl -k, verify=False or NODE_TLS_REJECT_UNAUTHORIZED=0 turn checking off. They prove quickly that TLS is the problem. Never leave them in code, scripts or CI (continuous integration).
Validate it works
Test from each client that was failing, with verification fully on. Start with curl:
curl -sS https://app.example.com/ -o /dev/null -w 'http=%{http_code} sslverify=%{ssl_verify_result}\n'
http=200 sslverify=0
ssl_verify_result uses the OpenSSL codes from step 2. Then test Python through requests, which covers certifi:
python3 -c "import requests; r = requests.get('https://app.example.com/', timeout=10); print(r.status_code)"
200
Then Node, with no overrides beyond the one you set on purpose:
node -e "require('https').get('https://app.example.com/', r => console.log(r.statusCode))"
200
Last, test from a machine you did not change, such as a CI runner. If only your repaired host succeeds, the server still needs the fix.
Troubleshooting
update-ca-certificates reports 0 added. The file must sit in /usr/local/share/ca-certificates/, end in .crt and hold PEM text. A .pem extension is skipped, and so is a DER (binary) file named .crt. Convert DER with openssl x509 -inform der -in root.cer -out root.crt.
The fix works in your shell but not from systemd or cron. Variables like SSL_CERT_FILE and NODE_EXTRA_CA_CERTS do not follow you into a service. Add them to the unit with Environment=, check with systemctl show your.service -p Environment, then run systemctl restart.
It works on the host and fails in the container. The image has its own /etc/ssl/certs, frozen at build time. In the Dockerfile, COPY the root into /usr/local/share/ca-certificates/ and run update-ca-certificates. Distroless and scratch images may have no trust store, so ship one.
Code 21 from monitoring, but the browser is happy. Browsers quietly repair broken chains with cached intermediates and AIA (Authority Information Access, a download link inside the certificate). Almost nothing else does. Believe openssl and fix the server. Verifying a certificate chain with openssl covers the mechanics in depth.
When this is the wrong approach
If a public service’s certificate is truly expired or names the wrong host, contact whoever runs it. Trusting their certificate to silence the error defeats a check that told you something true.
Certificate pinning fails differently. Apps that accept only a fixed set of certificates, often mobile SDKs and payment clients, ignore your trust store. An inspecting proxy breaks them until IT excludes that destination.
If the real job is getting an internal root onto every host, image and CI runner, automate it. Running an internal ACME certificate authority with step-ca shows one way.
curl’s SSL certificate page explains how clients find a trust store, and pip’s HTTPS certificates page lists its options.
If this is the kind of work you’d rather never own again, it’s the daily job of Managed Cloud Ops — book an infrastructure review.