"Hostname/IP mismatch, certificate is not valid for 'internal.acme.io'": the cert for the name you did not check

verbatim errorError: Hostname/IP does not match certificate's altnames: Host: internal.acme.io. is not in the cert's altnames: [DNS:api.acme.io, DNS:*.acme.io] code: 'ERR_TLS_CERT_ALTNAME_INVALID'

Problem

A service-to-service call to an internal hostname failed TLS validation while everything else worked:

Error: Hostname/IP does not match certificate's altnames: Host: internal.acme.io. is not in the cert's altnames: [DNS:api.acme.io, DNS:*.acme.io]
code: 'ERR_TLS_CERT_ALTNAME_INVALID'

Someone had pointed internal.acme.io at the same server as api.acme.io and assumed the cert would cover it. *.acme.io does not match internal.acme.io — and that surprises people every single time.

Root cause

Certificate matching is exact against the Subject Alternative Names, with exactly one wildcard rule: *.acme.io matches one leftmost label only — api.acme.io yes, internal.acme.io no (different leftmost label... wait: internal IS one label). The real gotchas, precisely:

*.acme.io matches internal.acme.io (one label) but NOT a.b.acme.io (two labels), and never the bare acme.io.
The certificate's CN is ignored by modern validators — only SANs count.
Multi-level domains need either a cert listing both names or a ..acme.io-style cert (rarely issued).
IP-address access (https://10.0.4.19) needs the IP in SANs; almost no cert has it.

fix preview — first 3 of 4 lines (bash), truncated:

openssl s_client -connect internal.acme.io:443 -servername internal.acme.io </dev/null 2>/dev/null | \
  openssl x509 -noout -ext subjectAltName
# X509v3 Subject Alternative Name:
… 1 more line in the fix

🔒 the fix — including 4 code blocks — is members-only. $1/mo unlocks everything.