Skip to content

Fix certificate verify failed (unable to get local issuer)

Fix the certificate verify failed error in Python, Node, Git, curl, Java, R or PowerShell by finding out which certificate is actually missing. You will read one OpenSSL result, repair the server chain or your trust store, and keep verification switched on.

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 code from openssl s_client and 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

  • openssl 1.1.1 or newer on the failing machine. The x509 -ext flag 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-certificates package 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.

Vertical chain for a current Let's Encrypt certificate: the leaf, intermediate YR1 and a cross-signed Root YR are sent by the server, and the ISRG Root X1 trust anchor is already on the client; missing intermediates give code 21 and a missing root gives code 20

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.

Decision tree from the openssl s_client command to four verify return code branches: code 0 means point the tool at the right CA file, code 10 means check dates and the clock, codes 19 or 20 mean install the proxy or internal root, code 21 means serve fullchain.pem

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.