Resolving `UNABLE_TO_VERIFY_LEAF_SIGNATURE` Error in Node.js with Custom CA Certificates

167 views

The UNABLE_TO_VERIFY_LEAF_SIGNATURE error typically occurs in Node.js when your application is unable to verify the SSL certificate of the server you're trying to connect to. This often happens when the server's SSL certificate chain is not recognized or there's an issue with the root CA certificates bundle that Node.js uses for verification.

One way to resolve this issue is to set the NODE_EXTRA_CA_CERTS environment variable to specify a custom CA certificates bundle that includes the necessary root certificates. Here’s how you can do it:

  1. Obtain a CA Certificates Bundle: Ensure you have a CA certificates bundle file. You can download Mozilla's CA certificates bundle, which is commonly used and recognized by many systems.

  2. Set the NODE_EXTRA_CA_CERTS Environment Variable:

    • On Linux/MacOS: Open your terminal and set the environment variable:

      export NODE_EXTRA_CA_CERTS=<path_to_your_ca_certificates_bundle>

      Replace <path_to_your_ca_certificates_bundle> with the absolute path to your CA certificates bundle file.

    • On Windows: Open Command Prompt and set the environment variable:

      set NODE_EXTRA_CA_CERTS=<path_to_your_ca_certificates_bundle>

      Or, if you're using PowerShell:

      $env:NODE_EXTRA_CA_CERTS="<path_to_your_ca_certificates_bundle>"

  3. Run Your Node.js Application: Now, start your Node.js application in the same terminal session where you set the environment variable. Your application should now use the specified certificates bundle for SSL verification.

Here’s an example of how you might set it up in a script:

# On Linux/MacOS:
#!/bin/bash
export NODE_EXTRA_CA_CERTS=/path/to/your/ca-certs.pem
node your-app.js

# On Windows (Command Prompt):
set NODE_EXTRA_CA_CERTS=C:\path\to\your\ca-certs.pem
node your-app.js

# On Windows (PowerShell):
$env:NODE_EXTRA_CA_CERTS="C:\path\to\your\ca-certs.pem"
node your-app.js

Example in Package.json Scripts (for Node.js Projects)

You can also add the environment variable setup in the scripts section of your package.json:

{
  "scripts": {
    "start": "NODE_EXTRA_CA_CERTS=/path/to/your/ca-certs.pem node your-app.js"
  }
}

Summary

By setting the NODE_EXTRA_CA_CERTS environment variable to point to a custom CA certificates bundle, you can resolve the UNABLE_TO_VERIFY_LEAF_SIGNATURE error in your Node.js application. This approach ensures that Node.js recognizes the necessary root certificates for SSL handshake processes.