tls: failed to verify certificate: x509: certificate is not valid for any names, but wanted to match localhost

When developing locally with TLS, you might encounter the error:

tls: failed to verify certificate: x509: certificate is not valid for any names, but wanted to match localhost

This error occurs when the certificate used for the connection does not match the expected hostname, i.e localhost.

By default, servers and clients expect valid TLS certificates that match the hostname they are connecting to. In this post, we'll explore the reasons behind this error and how to generate proper certificates with a valid subject alternative name (SAN). opensslWe'll build a sample Go service and client to test the solution.

Why?

In production environments, certificates are typically issued by trusted Certificate Authorities (CAs), ensuring that the certificate matches the host’s domain name. However, in development environments, we often use self-signed certificates for testing.

The client will reject the connection when a certificate is self-signed or generated without proper SANs. This is because the TLS certificate validation fails when it tries to match the localhost hostname with the certificate's SAN or Common Name (CN).

For example, when a client tries to connect to a service at https://localhost, the certificate might not include localhost as a valid name, causing the x509 error.