Node.js UNABLE_TO_VERIFY_LEAF_SIGNATURE: Causes, Fixes, and Troubleshooting
You are seeing UNABLE_TO_VERIFY_LEAF_SIGNATURE in a Node.js app, a CI job, or an npm install. This is a certificate-chain trust failure, not a generic network error. The fix is almost always one of two things: the server is not sending the intermediate certificate, or the certificate is issued by a private CA that Node.js does not trust by default.
This guide gives you commands to confirm the cause, production-safe fixes, a comparison table, and the exact error strings you will see when the cause is different.
What UNABLE_TO_VERIFY_LEAF_SIGNATURE Actually Means
Node.js validates the TLS certificate chain from the server’s leaf certificate up to a root CA in its trust store. The leaf is the end-entity certificate for your domain. UNABLE_TO_VERIFY_LEAF_SIGNATURE means Node could not build a valid path from that leaf to a trusted root.
Typical causes:
- The server sends only the leaf certificate and omits the intermediate CA certificate. This is the most common cause.
- The certificate is issued by an internal/private CA, and that root is not in Node.js’s CA bundle.
- Node.js is running in a container or old runtime with an outdated CA bundle.
- A corporate TLS inspection proxy replaces the certificate with one signed by a private CA.
The error usually appears like this:
Error: unable to verify the leaf certificate
at TLSSocket.onConnectSecure (node:_tls_wrap:1674:34)
at TLSSocket.emit (node:events:518:28)
at TLSSocket._finishInit (node:_tls_wrap:1085:8)
at TLSWrap.ssl.onhandshakedone (node:_tls_wrap:866:12) {
code: 'UNABLE_TO_VERIFY_LEAF_SIGNATURE'
}
Do not confuse it with ERR_TLS_CERT_ALTNAME_INVALID (hostname mismatch) or CERT_HAS_EXPIRED (expired certificate). Those have different fixes.
Quick Diagnosis: Is the Chain Incomplete?
Run these commands from the same network path as the failing Node.js process. Replace example.com with your hostname.
1. Inspect the certificate chain the server sends
openssl s_client -connect example.com:443 -servername example.com -showcerts </dev/null
In the output, count the certificate blocks. A healthy public chain normally shows at least the leaf certificate and one intermediate. You can list the subject and issuer lines:
openssl s_client -connect example.com:443 -servername example.com -showcerts </dev/null 2>/dev/null | grep -E '^ [0-9]+ s:|^ [0-9]+ i:'
If you see only one s: block and no intermediate issuer, the server chain is incomplete. That is your root cause.
2. Ask OpenSSL to verify the chain
openssl s_client -connect example.com:443 -servername example.com -verify_return_error </dev/null
Look for the verification line. Real failure examples:
Verify return code: 21 (unable to verify the first certificate)
Verify return code: 20 (unable to get local issuer certificate)
21 usually means the server did not send the intermediate. 20 usually means the verifier does not have the root CA, which is common with private CAs.
3. Reproduce with Node.js
node -e "require('https').get('https://example.com', r => console.log(r.statusCode)).on('error', e => console.error(e.code, e.message))"
If this prints UNABLE_TO_VERIFY_LEAF_SIGNATURE, you have reproduced the issue outside your application code.
4. Compare with curl
curl -vI https://example.com
If curl succeeds but Node.js fails, the difference is usually the trust store: curl often uses the system CA store, while Node.js uses its bundled CA store. If both fail with curl: (60) SSL certificate problem: unable to get local issuer certificate, fix the server chain first.
Fix 1: Complete the Certificate Chain on the Server
This is the most common fix. Configure the server to send the leaf plus all intermediate certificates. The file is usually called fullchain.pem.
Nginx
server {
listen 443 ssl;
server_name example.com;
ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
}
Do not point ssl_certificate at cert.pem alone. Use fullchain.pem.
Apache
SSLCertificateFile /path/to/fullchain.pem
SSLCertificateKeyFile /path/to/privkey.pem
# Older Apache versions may also need:
# SSLCertificateChainFile /path/to/chain.pem
Node.js HTTPS server
const https = require('https');
const fs = require('fs');
https.createServer({
key: fs.readFileSync('/etc/ssl/private/example.key'),
cert: fs.readFileSync('/etc/ssl/certs/fullchain.pem')
}, app).listen(443);
Build a fullchain file manually
The order matters: leaf certificate first, then intermediate certificates. The root is optional and often omitted.
cat server.crt intermediate.crt > fullchain.pem
openssl verify -CAfile /etc/ssl/certs/ca-certificates.crt fullchain.pem
Expected output:
fullchain.pem: OK
If you get unable to get local issuer certificate, the verifier’s CA file may not contain the root. Test with the intermediate explicitly:
openssl verify -CAfile /etc/ssl/certs/ca-certificates.crt -untrusted intermediate.crt server.crt
After changing the certificate, validate and reload:
sudo nginx -t && sudo systemctl reload nginx
Fix 2: Trust a Private CA with NODE_EXTRA_CA_CERTS
If the certificate is valid but issued by an internal CA, Node.js needs that root CA. The safest process-wide fix is the NODE_EXTRA_CA_CERTS environment variable. It appends your CA to Node.js’s default trust store; it does not replace it.
NODE_EXTRA_CA_CERTS=/etc/ssl/private/company-root.pem node app.js
Requirements and behavior:
- The value must be a path to a PEM file, not a directory.
- The file can contain one or more PEM-encoded CA certificates.
- Node.js reads it at process startup; restart the process after changing it.
- It applies to the process and child processes that inherit the environment.
Docker / Alpine example
FROM node:20-alpine
COPY company-root.pem /usr/local/share/ca-certificates/company-root.crt
RUN update-ca-certificates
ENV NODE_EXTRA_CA_CERTS=/usr/local/share/ca-certificates/company-root.crt
COPY . /app
WORKDIR /app
CMD ["node", "app.js"]
Windows PowerShell
$env:NODE_EXTRA_CA_CERTS = 'C:/certs/company-root.pem'
node app.js
Verify the connection
node -e "require('https').get('https://internal.example.com', r => console.log(r.statusCode)).on('error', e => console.error(e.code, e.message))"
If it still fails, confirm you are using the correct root CA, not an intermediate. A root CA has CA:TRUE and is self-signed; an intermediate is signed by another CA.
Fix 3: Set the CA Per Request in Code
Use this when you only want to trust a private CA for specific requests, or when you cannot change the process environment.
const https = require('https');
const fs = require('fs');
const ca = fs.readFileSync('/etc/ssl/private/company-root.pem');
https.get('https://internal.example.com', { ca }, (res) => {
console.log(res.statusCode);
res.resume();
}).on('error', (err) => {
console.error(err.code, err.message);
});
To keep the default public roots and add your private CA, combine them:
const tls = require('tls');
const fs = require('fs');
const ca = [
...tls.rootCertificates,
fs.readFileSync('/etc/ssl/private/company-root.pem', 'utf8')
];
Axios
const https = require('https');
const fs = require('fs');
const axios = require('axios');
const httpsAgent = new https.Agent({
ca: fs.readFileSync('/etc/ssl/private/company-root.pem')
});
axios.get('https://internal.example.com', { httpsAgent });
node-fetch
const fetch = require('node-fetch');
const https = require('https');
const fs = require('fs');
const agent = new https.Agent({
ca: fs.readFileSync('/etc/ssl/private/company-root.pem')
});
fetch('https://internal.example.com', { agent });
Scope this narrowly. Do not set rejectUnauthorized: false as a shortcut; it disables the verification you are trying to fix.
Comparison Table: Which Fix Should You Use?
| Fix | Best for | Scope | Production-safe | Command / code |
|---|---|---|---|---|
| Complete server chain | Missing intermediate certificate | All clients | Yes | ssl_certificate .../fullchain.pem |
NODE_EXTRA_CA_CERTS |
Private or internal CA | Process and child processes | Yes | NODE_EXTRA_CA_CERTS=root.pem node app.js |
ca option |
Per-request custom trust | One request or agent | Yes, if scoped | https.get(url, { ca }) |
| Update Node.js / OS CA bundle | Outdated trust store | Runtime or system | Yes | nvm install --lts; apt install ca-certificates |
--use-system-ca (newer Node.js) |
Use OS trust store instead of bundled roots | Process | Yes, if supported | node --use-system-ca app.js |
NODE_TLS_REJECT_UNAUTHORIZED=0 |
Local debugging only | Entire process | No | Never in production |
checkServerIdentity |
Hostname mismatch, not chain failure | One request | Only with a deliberate policy | Custom callback |
Check whether your Node.js supports system CA mode before relying on it:
node --help | grep use-system-ca
Troubleshooting: Real Error Messages and What They Mean
UNABLE_TO_VERIFY_LEAF_SIGNATURE — unable to verify the leaf certificate
Meaning: Node cannot build a chain from the leaf to a trusted root. Fix: send the intermediate certificate (fullchain) or add the private root with NODE_EXTRA_CA_CERTS.
UNABLE_TO_GET_ISSUER_CERT_LOCALLY — unable to get local issuer certificate
Meaning: Node reached the top of the chain it received but does not have the issuer/root CA locally. Fix: install or update ca-certificates, or point NODE_EXTRA_CA_CERTS at the private root. On Debian/Ubuntu:
sudo apt-get update && sudo apt-get install --reinstall ca-certificates
SELF_SIGNED_CERT_IN_CHAIN — self signed certificate in certificate chain
Meaning: The chain contains a self-signed certificate that Node does not trust. This is very common behind a corporate TLS inspection proxy. Fix: export the proxy root CA and set NODE_EXTRA_CA_CERTS. For npm:
npm config set cafile /path/to/company-root.pem
DEPTH_ZERO_SELF_SIGNED_CERT — self signed certificate
Meaning: The server’s leaf certificate is self-signed. Fix: use a certificate from a trusted CA, or explicitly trust that self-signed certificate as a CA for the request.
CERT_HAS_EXPIRED — certificate has expired
Meaning: The certificate is outside its validity period. Fix: renew it and reload the server. Check dates with:
openssl s_client -connect example.com:443 -servername example.com </dev/null 2>/dev/null | openssl x509 -noout -dates
ERR_TLS_CERT_ALTNAME_INVALID — Hostname/IP does not match certificate's altnames
Meaning: The certificate chain is trusted, but the hostname you connected to is not listed in the certificate’s Subject Alternative Names. Fix: connect using a name in the SAN, or issue a certificate that includes the correct hostname. This is not fixed by adding a CA.
curl: (60) SSL certificate problem: unable to get local issuer certificate
Meaning: curl has the same chain problem. Fix: complete the server chain. This confirms the issue is server-side, not Node-specific.
OpenSSL verify error:num=21 or num=20
Meaning: num=21 is usually a missing intermediate; num=20 is a missing local root. Fix: use fullchain on the server for 21; install or trust the root for 20.
NODE_TLS_REJECT_UNAUTHORIZED=0: Debug Only, Never Production
Setting NODE_TLS_REJECT_UNAUTHORIZED=0 disables certificate verification for every TLS connection in the process, including outbound calls to third-party APIs. Node.js prints a warning:
Warning: Setting the NODE_TLS_REJECT_UNAUTHORIZED environment variable to '0' makes TLS connections and HTTPS requests insecure by disabling certificate verification.
Use it only for a short local test against a known host, for example:
NODE_TLS_REJECT_UNAUTHORIZED=0 node local-test.js
Do not put it in .env, Dockerfiles, CI variables, or production manifests. The correct production alternatives are a complete server chain, NODE_EXTRA_CA_CERTS, or a scoped ca option.
FAQ
Does NODE_EXTRA_CA_CERTS replace Node.js’s default CA list?
No. It appends the certificates in the file to the default trust store. Public sites continue to work, and your private CA becomes trusted for that process.
Can NODE_EXTRA_CA_CERTS point to a directory?
No. It must be a file path. The file may contain multiple PEM certificates concatenated together.
Why does curl work but Node.js fails with UNABLE_TO_VERIFY_LEAF_SIGNATURE?
curl commonly uses the operating system trust store, while Node.js ships its own bundled CA store. A private CA may be installed system-wide but still be missing from Node.js. Use NODE_EXTRA_CA_CERTS or the ca option.
Is fullchain.pem the same as cert.pem?
No. cert.pem usually contains only the leaf certificate. fullchain.pem contains the leaf plus the intermediate certificate(s). Servers should send the fullchain.
Does the order of certificates in fullchain.pem matter?
Yes. Put the leaf certificate first, then the intermediate(s). The root is optional. Wrong order can cause chain-building failures in some clients.
How do I fix this in a Docker container?
Install ca-certificates, copy your private root into the image, run update-ca-certificates, and set NODE_EXTRA_CA_CERTS to the copied PEM file. For public sites, keeping the base image’s CA package up to date is usually enough.
Should I use rejectUnauthorized: false?
Only for isolated debugging. It disables certificate verification and exposes the process to man-in-the-middle attacks. Prefer ca with the correct root certificate.
How can I check which Node.js version and CA behavior I have?
Run node -v. Node.js generally uses a bundled CA store; newer releases may support --use-system-ca. Check with node --help | grep use-system-ca. If the flag is unavailable, use NODE_EXTRA_CA_CERTS for private roots.