ERR_TLS_CERT_ALTNAME_INVALID
The server's certificate SAN names do not match the requested hostname.
Usually happens because:
- ☑ IP Query Mismatches
- ☑ Subdomain Mismatches
- ☑ Mismatched domain targets
🔍 Quick Checklist:
What is ERR_TLS_CERT_ALTNAME_INVALID?
The ERR_TLS_CERT_ALTNAME_INVALID error is thrown by Node.js HTTPS client modules when the host requested in your query does not match any of the DNS domain names or IP addresses defined inside the Subject Alternative Name (SAN) fields of the remote server's SSL/TLS certificate.
Common Causes
- IP Query Mismatches: Requesting IP addresses directly when the SSL cert is only valid for names.
- Subdomain Mismatches: Querying subdomains that are not mapped inside wildcard cert configs.
- Mismatched domain targets: Connecting to hostnames that host incorrect cert bindings.
| Cause | Frequency |
|---|---|
| IP Query Mismatches | ⭐⭐⭐⭐⭐ |
| Subdomain Mismatches | ⭐⭐⭐⭐ |
| Mismatched domain targets | ⭐⭐⭐ |
Common Mistakes
- Disabling TLS certification validation (rejectUnauthorized: false) in production environments (opens the system to MITM credentials hijacking).
How to Fix
Framework-Specific Examples
Globally disabling TLS checking for local staging setups (Caution: Never use in production).
if (process.env.NODE_ENV === 'development') {
process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0';
}Server Configuration Examples
Aligning server domain naming configs inside Nginx SSL blocks.
server {
listen 443 ssl;
server_name realdomain.com;
ssl_certificate /path/to/cert.pem;
}Best Practices
- Acquire valid wildcard SSL certificates (via Let's Encrypt) to cover all subdomains.
Frequently Asked Questions (FAQ)
Q: What triggers a altname invalid error?
It happens when the host requested in the URL does not match any of the DNS names or IP addresses listed in the Subject Alternative Name (SAN) section of the server's certificate.
Q: What is process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0'?
It is an environment flag that tells Node.js to ignore all TLS certificate validation checks. It is highly insecure and should never be used in production.
Q: Does Let's Encrypt prevent this error?
Yes. Let's Encrypt issues valid certificates that match your public domain name, preventing altname mismatch errors.
Q: Can I bind a certificate to an IP address directly?
Yes. You must generate a certificate that lists the IP address inside the Subject Alternative Name (SAN) fields explicitly.