No subject alternative DNS name matching api.example.com found.

The host is the one from your URL. JDK 21 and 25 prefix the TLS alert: "(certificate_unknown) No subject alternative DNS name matching … found.". Certificates without any SAN extension, or IP-address URLs, produce "No subject alternative names present" and "No subject alternative names matching IP address … found" instead.

Java (JSSE HostnameChecker) — java.security.cert.CertificateException inside SSLHandshakeException

What it means

The certificate chain is trusted, but Java's hostname check (HTTPS endpoint identification) found no DNS entry in the certificate's Subject Alternative Name extension that matches the host in the URL. Java quotes the host it was asked to reach. Since the certificate has a SAN extension, its Common Name is not considered.

Why it happens

• The certificate does not cover this host name

  common

  The certificate was issued for other names (www., the apex domain, an old service name); a wildcard covers only one label.

• The client uses an internal alias or service name

  common

  Kubernetes service names, docker-compose aliases and load-balancer host names reach the right server but are not in a certificate issued for the public name.

• The server returned another site's certificate

  occasional

  On shared endpoints the certificate depends on SNI; an unconfigured name gets the default certificate.

How to fix it

1. 1.

   List the certificate's names

   openssl or keytool -printcert -sslserver shows the SubjectAlternativeName entries to compare with the URL.

   echo | openssl s_client -connect api.example.com:443 -servername api.example.com 2>/dev/null \
     | openssl x509 -noout -ext subjectAltName
   # or with Java's own tool
   keytool -printcert -sslserver api.example.com:443 | grep -A3 SubjectAlternativeName

2. 2.

   Reissue the certificate with the missing names

   Request every DNS name clients use; keytool's -ext SAN=dns:…,dns:… adds them to the CSR.

   # Java keystores: request a certificate with every name in the SAN extension
   keytool -certreq -alias server -keystore server.p12 -ext "SAN=dns:api.example.com,dns:www.example.com" -file server.csr

3. 3.

   Connect with a name the certificate lists

   Keep hostname verification on and change the URL (and name resolution) instead; a HostnameVerifier that accepts everything removes the protection TLS exists for.

   // Use the name in the certificate in the URL; resolve it to the address you need
   // (DNS, /etc/hosts or a custom resolver), instead of connecting by IP or alias.
   HttpRequest req = HttpRequest.newBuilder(URI.create("https://www.example.com/health")).build();

← Browse the full signature error database