Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท CLI Flags

Node.js NODE_EXTRA_CA_CERTS environment variable

Reference for NODE_EXTRA_CA_CERTS: add corporate or private certificate authorities to Node.js without turning off TLS verification, with a runnable check.

Node.js ships with its own list of trusted root certificate authorities (CAs), copied from Mozilla's list, instead of using the operating system's store. If your company runs a TLS-inspecting proxy, or a staging server uses a certificate signed by a private CA, fetch() and https.request() fail with errors such as UNABLE_TO_VERIFY_LEAF_SIGNATURE or SELF_SIGNED_CERT_IN_CHAIN.

NODE_EXTRA_CA_CERTS fixes that the safe way. Set it to the path of a PEM file containing one or more certificates, and Node adds them to the trusted list for the whole process. Verification stays on; you only widen who is trusted.

NODE
// shell: NODE_EXTRA_CA_CERTS=/etc/ssl/company-ca.pem node app.js

Try it

Node.js Extra certificates appear in the trust store

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js A missing file is only a warning

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Syntax

NODE
// NODE_EXTRA_CA_CERTS=/path/to/file.pem
// tls.getCACertificates(type?: 'default' | 'system' | 'bundled' | 'extra'): string[]
// tls.rootCertificates: string[]    // the bundled roots only
Part Description
File A PEM file; concatenate several -----BEGIN CERTIFICATE----- blocks to trust several CAs.
'bundled' The Mozilla list built into Node.
'extra' Certificates loaded from NODE_EXTRA_CA_CERTS.
'default' What a new TLS connection trusts: bundled plus extra (and system certificates when --use-system-ca is on).

Usage notes

  • Read once, at process start. Setting process.env.NODE_EXTRA_CA_CERTS from inside the program has no effect. Set it in the shell, the service definition, the Dockerfile ENV, or the env option of child_process.
  • Missing or unreadable file: Node prints a warning and continues with the built-in list. The file is loaded lazily, when TLS certificates are first needed, so the warning can appear later than process start (or never, in a program that never uses TLS). A silent fallback is easy to miss in logs, so check for the warning when a certificate error persists.
  • It adds, never removes. You cannot use it to distrust a built-in CA.
  • Applies to everything in the process: https, tls, http2 and fetch(). An individual request can still narrow trust with the ca option, which replaces the default list for that connection.
  • System store: newer Node releases can also read the OS certificate store through the --use-system-ca flag. Check tls.getCACertificates('system') on your version before relying on it.
  • Prefer it to disabling checks. NODE_TLS_REJECT_UNAUTHORIZED=0 turns off protection for every connection; adding the one CA you need keeps protection for all others.
  • File content only. The file must hold public certificates. Never put private keys in it.
  • Containers: copy the CA file into the image and set the variable in the Dockerfile; there is no need to run update-ca-certificates for Node.