Fix UNABLE_TO_GET_ISSUER_CERT_LOCALLY Error in Node.js

What Does UNABLE_TO_GET_ISSUER_CERT_LOCALLY Error Mean?

The “UNABLE_TO_GET_ISSUER_CERT_LOCALLY” error in Node.js applications occurs when the certificate authority (CA) that issued the SSL/TLS certificate cannot be found in the local trust store. This prevents the application from being able to verify the authenticity of the certificate.

This error commonly occurs when using self-signed certificates or certificates issued by a private CA. It can also happen if the root and intermediate CA certificates are not properly bundled with the server certificate.

Key Takeaways

Step-by-Step Guide to Fix UNABLE_TO_GET_ISSUER_CERT_LOCALLY Error in Node JS

Here is a step-by-step guide to troubleshoot and fix the “unable to get issuer certificate locally” error in Node.js:

1. Identify the Problematic Certificate

The first step is to identify which certificate is causing the issue.

If you are using Express, you can get the certificate details by adding an error handler:

const express = require('express');
const https = require('https');
const fs = require('fs');
const app = express();
const options = {
  key: fs.readFileSync('/path/to/private.key'),
  cert: fs.readFileSync('/path/to/certificate.crt')
};
const server = https.createServer(options, app);
server.on('error', (error) => {
  console.log('Caught exception: ' + error.message);
  console.log('Certificate details: ' + error.context.cert);
});
server.listen(3000);

This will log the problematic certificate when the error occurs.

If you are not using Express, you can access the certificate from the socket.getPeerCertificate() method on the TLS socket.

2. Verify Certificate Chain

Once you have the certificate, the next step is to validate that the chain of trust is properly established.

You need to ensure that the server certificate was signed by an intermediate CA certificate, which was then signed by a trusted root CA certificate.

On Linux/macOS, you can inspect the certificate chain using openssl:

openssl x509 -in /path/to/certificate.crt -text -noout

Look for the Authority Key Identifier and Subject Key Identifier to match the chain.

You can also use openssl verify to validate the chain:

openssl verify -verbose -CAfile ca-chain.cert /path/to/certificate.crt

This will attempt to build the chain and verify the certificate.

On Windows, you can use CertUtil:

certutil -verify /path/to/certificate.crt

If the chain is broken, you will need to bundle the intermediate and root CA certs with your server certificate to resolve it.

3. Check Trusted Root CA Store

Another cause of the error is if the root CA certificate is not trusted by Node.js/the operating system.

Node.js uses the system’s root CA store by default. On Linux, this is usually /etc/ssl/certs/ca-certificates.crt. On macOS, it’s /etc/pki/tls/certs/ca-bundle.crt. On Windows, it’s the system root CA store.

To see if the root CA is trusted, view the certificate, and compare the issuer name and public key hash to the certificates in the root store.

If it is missing from the trusted root store, you need to add the root CA certificate there so applications will trust certificates issued by it.

On Linux:

sudo cp /path/to/rootCA.pem /usr/local/share/ca-certificates/
sudo update-ca-certificates

On macOS:

sudo security add-trusted-cert -d -r trustRoot /path/to/rootCA.pem

On Windows, use the Certificate Import Wizard to add it to the Trusted Root Certification Authorities store.

4. Set Node.js CA Cert Option

If adding the root CA to the system store is not possible, you can configure Node.js to use a custom CA store instead.

When creating the HTTPS server, specify the ca option pointing to your pem file with the trusted CA certs:

const https = require('https');
const options = {
  key: ...,
  cert: ...,
  ca: fs.readFileSync('/path/to/ca-cert.pem')
};
https.createServer(options, app);

This will make Node.js use the CAs in that file to verify connections rather than the system store.

5. Use Self-signed Certificates for Development

When developing or testing locally, you can use a self-signed certificate instead to avoid SSL certificate errors.

openssl req -x509 -newkey rsa:4096 -nodes -sha256 -keyout cert.key -out cert.crt -days 365

Then launch your Node.js server using the self-signed cert:

const fs = require('fs');
const https = require('https');
const options = {
  key: fs.readFileSync('cert.key'),
  cert: fs.readFileSync('cert.crt')
};
https.createServer(options, app).listen(3000);

The server will now use the self-signed certificate without trust issues.

6. UseOpenSSL on Windows

The commands above use OpenSSL which is not installed by default on Windows.

To use OpenSSL on Windows:

This will allow you to generate certificates, inspect them, and build chains.

7. Troubleshoot Module Issues

In some cases, the issue may be caused by bugs in native modules Node.js relies on:

Rebuilding modules with npm rebuild can also help resolve inconsistencies.

Final Thoughts

The “UNABLE_TO_GET_ISSUER_CERT_LOCALLY” error occurs when Node.js cannot verify the authenticity of a certificate due to a missing certificate authority. Troubleshooting involves inspecting the certificate chain to ensure it is complete, validating the root CA is trusted, and properly configuring certificate trusts stores. The root cause is often incomplete chains, untrusted CAs, or missing intermediate certs. Best practices are obtaining certificates from trusted CAs, bundling all intermediate and root certs, and adding root CAs to trust stores. Following these certificate configuration and validation steps will resolve the error and establish robust SSL/TLS trust verification in Node.js applications. Proper certificate handling is crucial for avoiding connection issues caused by incomplete certificate chains and untrusted authorities.

FAQs About UNABLE_TO_GET_ISSUER_CERT_LOCALLY

1. What causes the “unable to get issuer certificate locally” error?

This error is caused when Node.js cannot find the certificate authority (CA) that issued the certificate locally in order to verify the authenticity of the certificate. This typically happens with self-signed certificates or when the certificate chain is incomplete.

2. What is a certificate chain?

A certificate chain is a sequence of certificates required to validate a certificate. It starts with the server certificate, then each issuing intermediate CA certificate, and ends with the trusted root CA certificate. Each cert in the chain is signed by the next one to establish trust.

3. How do I inspect certificate chains on Windows?

On Windows you can use the CertUtil command line tool to inspect and validate certificate chains. Examples:

View certificate details:

certutil -v -dump /path/to/certificate.crt

Build and validate chain:

certutil -verify /path/to/certificate.crt

4. Can I use self-signed certificates in production?

Self-signed certificates should only be used for development/testing purposes. They will cause SSL/TLS errors as they are not signed by a trusted CA. For production use, you need a valid SSL/TLS certificate signed by a trusted CA.

5. What is the best practice for fixing this error?

The best practice is to properly configure your SSL/TLS certificates and trust stores:

This provides robust certificate validation and avoids “UNABLE_TO_GET_ISSUER_CERT_LOCALLY” errors.

Priya Mervana

Verified Web Security Experts

Priya Mervana is working at SSLInsights.com as a web security expert with over 10 years of experience writing about encryption, SSL certificates, and online privacy. She aims to make complex security topics easily understandable for everyday internet users.