# TLS certificate hostname mismatch: the certificate's CN or SAN does not match the requested hostname

- **ID:** `security/tls-certificate-hostname-mismatch`
- **Domain:** security
- **Category:** tls_error
- **Error Code:** `TLS-1002`
- **Verification:** ai_generated
- **Fix Rate:** 90%

## Root Cause

The TLS certificate presented by the server has a Common Name (CN) or Subject Alternative Name (SAN) that does not match the hostname used in the client's request, causing the TLS handshake to fail.

## Version Compatibility

| Version | Status | Introduced | Deprecated |
|---------|--------|------------|------------|
| OpenSSL 3.0 | active | — | — |
| Java 17 | active | — | — |
| Node.js 20 | active | — | — |
| Nginx 1.24 | active | — | — |

## Workarounds

1. **Reissue the certificate with the correct hostname in the SAN field. For Let's Encrypt: `certbot certonly --standalone -d example.com -d www.example.com` and ensure all alternative names are included.** (95% success)
   ```
   Reissue the certificate with the correct hostname in the SAN field. For Let's Encrypt: `certbot certonly --standalone -d example.com -d www.example.com` and ensure all alternative names are included.
   ```
2. **If using a reverse proxy, configure SNI (Server Name Indication) to serve the correct certificate based on the hostname. For Nginx: `server_name example.com; ssl_certificate /path/to/cert.pem;`** (85% success)
   ```
   If using a reverse proxy, configure SNI (Server Name Indication) to serve the correct certificate based on the hostname. For Nginx: `server_name example.com; ssl_certificate /path/to/cert.pem;`
   ```

## Dead Ends

- **** — Disabling hostname verification entirely (e.g., setting `NODE_TLS_REJECT_UNAUTHORIZED=0`) bypasses the error but exposes the connection to man-in-the-middle attacks. (70% fail)
- **** — Adding the hostname to the /etc/hosts file to point to a different IP doesn't fix the certificate mismatch; the server still presents the wrong cert for that hostname. (40% fail)
- **** — Some try to use a self-signed certificate with the correct hostname but forget to add the CA to the trust store, causing a different error (unable to verify certificate). (30% fail)