TLS certificate SAN contains an invalid character
Production Risk
Clients will reject connections to servers with malformed SANs; fix at certificate issuance time.
Thrown when a Subject Alternative Name (SAN) in a TLS certificate contains characters that are not permitted. This error is raised during parsing of the certificate SAN, usually when the SAN contains non-ASCII or otherwise invalid characters that cannot be represented in the expected format.
- 1Certificate SAN contains non-ASCII characters in a DNS name entry
- 2Malformed or corrupt certificate with invalid SAN encoding
- 3Using internationalized domain names (IDN) without proper punycode encoding in SAN
Triggered when the TLS stack parses a certificate and encounters an invalid SAN value.
// The error originates from certificate parsing, not user code
// A certificate with a SAN like DNS:héllo.example.com would trigger this
const tls = require('tls');
const socket = tls.connect({ host: 'example.com', port: 443 });
socket.on('error', (err) => {
if (err.code === 'ERR_TLS_CERT_ALTNAME_FORMAT') {
console.error('Bad cert SAN format');
}
});expected output
Error [ERR_TLS_CERT_ALTNAME_FORMAT]: Invalid character in subject alternative name
Fix
Use properly encoded SANs in your certificate
WHEN When generating certificates with IDN hostnames
# Convert IDN to punycode before including in the SAN # héllo.example.com -> xn--hllo-bpa.example.com openssl req -new -key key.pem -out csr.pem -subj "/CN=xn--hllo-bpa.example.com"
Why this works
Punycode encoding represents non-ASCII domain names in ASCII, which is valid in certificate SANs.
// The error originates from certificate parsing, not user code
// A certificate with a SAN like DNS:héllo.example.com would trigger this
const tls = require('tls');
const socket = tls.connect({ host: 'example.com', port: 443 });
socket.on('error', (err) => {
if (err.code === 'ERR_TLS_CERT_ALTNAME_FORMAT') { // this triggers ERR_TLS_CERT_ALTNAME_FORMATtry {
// operation that may throw ERR_TLS_CERT_ALTNAME_FORMAT
riskyOperation()
} catch (err) {
if (err.code === 'ERR_TLS_CERT_ALTNAME_FORMAT') {
console.error('ERR_TLS_CERT_ALTNAME_FORMAT:', err.message)
} else {
throw err
}
}// Validate inputs before calling the operation
function safe_err_tls_cert_altname_format(...args) {
// validate args here
return performOperation(...args)
}✕ Include raw Unicode characters in certificate SAN DNS entries
Certificate SANs must use ASCII or punycode; raw Unicode is invalid and causes parse errors.
Node.js Error Codes Documentation
Content generated with AI assistance and reviewed for accuracy. Found an error? hello@errcodes.dev