Maaz Zindani

Loading the index…

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

Node.js says the hostname does not match the certificate's altnames

ErrorError: Hostname/IP does not match certificate's altnames

Short answer

Node.js compares the host you connect to with the subjectAltName entries of the server certificate. If none match, the TLS call fails with ERR_TLS_CERT_ALTNAME_INVALID. Read the certificate's SAN list, connect using a name that is in it, or reissue the certificate with the name you use.

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

Fix it fast

  1. 1Find out which cause you have

    Print the names the server certificate really carries, and compare them with the host in your URL.

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

    1. 1The SAN output lacks your hostname, or shows only another domainThe certificate does not list the name you connect toFix
    2. 2The URL uses an IP address, localhost, a container name or a load balancer nameThe client connects by an IP or an internal name, not the name on the certificateFix
    3. 3The SAN list shows URI: entries but no DNS: or IP Address: entry for the hostThe only matching entry is a URI subject alternative nameFix

What does the error look like?

  • Error: Hostname/IP does not match certificate's altnames
  • code: 'ERR_TLS_CERT_ALTNAME_INVALID'

Cause 1 of 3

The certificate does not list the name you connect to

1Check

Node.js documents this error as a host name or IP that did not match any of the subjectAltNames in the certificate. Print the SAN list from the server and from a saved certificate file.

openssl x509 -in cert.pem -noout -ext subjectAltName
openssl x509 -in cert.pem -noout -subject

2Fix

Issue a new certificate whose subjectAltName contains every name clients use (each hostname, and each IP if clients connect by IP), and install it on the server.

openssl x509 -in new-cert.pem -noout -ext subjectAltName

3Verify

Repeat the first command against the server; your hostname must now be in the list, then run the Node.js request again.

node -e "require('https').get('https://example.com',r=>console.log(r.statusCode))"

Confirmed by nodejs.org

Did this fix it?

Cause 2 of 3

The client connects by an IP or an internal name, not the name on the certificate

1Check

The check uses the host name of the connection (or the servername option when set). The tls.connect docs say servername must be a host name and not an IP address.

grep -rn -E "https?://[0-9.]+|servername" src

2Fix

Use the DNS name that is in the certificate in the URL. If the connection must go to a different address, set that name as the servername option, so the certificate is checked against the right name.

import https from 'node:https';

https.get({
  host: '10.0.0.12',        // where to connect
  servername: 'api.example.com', // name the certificate must match
  path: '/health',
}, (res) => console.log(res.statusCode));

3Verify

The request returns a status code instead of the altnames error.

node client.mjs

Confirmed by nodejs.org

Did this fix it?

Cause 3 of 3

The only matching entry is a URI subject alternative name

1Check

The Node.js docs say a matching uniformResourceIdentifier SAN is not accepted for a host name, and support for accepting it was removed after CVE-2021-44531. Print the SAN extension and look at the entry types.

openssl x509 -in cert.pem -noout -ext subjectAltName

2Fix

Reissue the certificate with DNS (or IP) entries for the host. Only if you control both sides and cannot reissue, the docs allow a custom checkServerIdentity function that implements the behavior you accept; keep rejectUnauthorized on.

const tls = require('node:tls');

const options = {
  host: 'internal.example.com',
  port: 443,
  checkServerIdentity: (servername, cert) => {
    // call the built-in check, then add your own narrow rule if needed
    return tls.checkServerIdentity(servername, cert);
  },
};

3Verify

Connect again; the SAN list should now carry a DNS or IP entry for the host.

openssl x509 -in new-cert.pem -noout -ext subjectAltName

Confirmed by nodejs.org

Did this fix it?

How do I stop it coming back?

  • Put every public and internal hostname in the certificate's SAN list when you request it.
  • Use one canonical DNS name per service in client configuration, not raw IPs.
  • Do not set rejectUnauthorized to false to silence this error; that turns off the check for the whole connection.

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

Strapi admin blocks uploaded images and media because of its CSP

Refused to load media from 'https://bucket.s3.eu-west-1.amazonaws.com/...' because it violates the following Content Security Policy directive: "media-src 'self' data: blob:".

Strapi's default strapi::security middleware limits images and media to 'self'.

2 causes, each with a fix

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

Next step

Want this handled for good?

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