Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

Node.js refuses a self-signed certificate on https.request

ErrorDEPTH_ZERO_SELF_SIGNED_CERT

Short answer

Node.js rejects a certificate that no trusted authority signed, with codes like DEPTH_ZERO_SELF_SIGNED_CERT. Do not switch verification off. Give Node.js the certificate or the private CA instead: the ca option for one client, or NODE_EXTRA_CA_CERTS for the whole process. Disabling checks is for local development only.

  • Applies to Node.js 22, Node.js 24
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Find out which certificate the server really sends, and who issued it. If subject and issuer are the same, it is self-signed.

    openssl s_client -connect internal.example.com:443 -servername internal.example.com </dev/null 2>/dev/null | openssl x509 -noout -subject -issuer
  2. 2Match what you see, then jump to its fix

    1. 1The error code appears on one https.request call to your own server, a staging host or a device on the LAN.One client talks to a server with a self-signed or private-CA certificateFix
    2. 2The same error comes from several modules (an SDK, fetch, an HTTP client), and you cannot edit their options.Many libraries in the same process need to trust the same private CAFix
    3. 3curl works on the same server, Node.js fails. Node.js adds a hint about --use-system-ca to the error.The root CA is installed on the machine but Node.js does not use the system storeFix
    4. 4A throw-away script against localhost with a certificate you generated a minute ago.Local development only: verification switched offFix

What does the error look like?

  • DEPTH_ZERO_SELF_SIGNED_CERT
  • UNABLE_TO_GET_ISSUER_CERT

Cause 1 of 4

One client talks to a server with a self-signed or private-CA certificate

1Check

Confirm you have the server certificate (or the CA certificate that signed it) as a PEM file. https.request accepts the ca option, so Node.js can verify against that file.

openssl x509 -in my-root-ca.pem -noout -subject -dates

2Fix

Pass the PEM file in the ca option and keep rejectUnauthorized at its default of true. When ca is set, Node.js uses only that list for this client.

const https = require('node:https');
const fs = require('node:fs');

const options = {
  hostname: 'internal.example.com',
  port: 443,
  path: '/',
  method: 'GET',
  ca: fs.readFileSync('my-root-ca.pem'),
};
options.agent = new https.Agent(options);
https.request(options, (res) => console.log(res.statusCode)).end();

3Verify

The request now returns a status code instead of an error event.

node request.js

Confirmed by nodejs.org

Did this fix it?

Cause 2 of 4

Many libraries in the same process need to trust the same private CA

1Check

Check whether the process was started with the extra CA variable. It is only read when the process starts.

echo "$NODE_EXTRA_CA_CERTS"

2Fix

Start Node.js with NODE_EXTRA_CA_CERTS pointing at a PEM file. It adds your certificates to the built-in list. It does not apply to clients that set the ca option themselves.

NODE_EXTRA_CA_CERTS=/etc/ssl/my-root-ca.pem node server.js

3Verify

Run the failing call again. Changing process.env.NODE_EXTRA_CA_CERTS after start-up has no effect, so restart the process.

NODE_EXTRA_CA_CERTS=/etc/ssl/my-root-ca.pem node request.js

Confirmed by nodejs.org

Did this fix it?

Cause 3 of 4

The root CA is installed on the machine but Node.js does not use the system store

1Check

Node.js appends a hint to certificate errors when the root CA may be installed locally. Read the full error message.

node request.js 2>&1 | head -n 20

2Fix

Run Node.js with the --use-system-ca flag, as the hint suggests, so it also reads the operating system trust store.

node --use-system-ca request.js

3Verify

Run the same script again.

node --use-system-ca request.js

Confirmed by nodejs.org

Did this fix it?

Cause 4 of 4

Local development only: verification switched off

1Check

Be sure the host is your own dev machine. The docs call disabling validation insecure.

echo "$NODE_TLS_REJECT_UNAUTHORIZED"

2Fix

Prefer the ca option. If you must, set rejectUnauthorized: false on that one request, never through the process-wide environment variable, and never in production.

const agent = new https.Agent({ rejectUnauthorized: false });
https.get('https://localhost:8443/', { agent }, (res) => console.log(res.statusCode));

3Verify

The call works on localhost. Delete the option before the code leaves your machine.

grep -rn "rejectUnauthorized\|NODE_TLS_REJECT_UNAUTHORIZED" src/

Confirmed by nodejs.org

Did this fix it?

How do I stop it coming back?

  • Issue the dev and staging certificates from a small private CA, and distribute only that CA file.
  • Search the code base and CI config for NODE_TLS_REJECT_UNAUTHORIZED before each release.
  • Keep the CA file in the repository's config or secrets, with its expiry date noted.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Back end

ng serve says it cannot determine the project or target

Cannot determine project for command.

The Angular CLI looked through angular.json for a project that defines the target you asked for (serve, build, test) and found none, or found several and could not pick one.

3 causes, each with a fix

Back end

ng serve cannot find the dev-server builder package

Could not find the implementation for builder @angular/build:dev-server

The builder named in angular.json (for example @angular-devkit/build-angular:dev-server) is looked up as an npm package starting from the workspace root.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.