GENERAL: What should I do if I get an “x509: certificate relies on legacy Common Name field” error?

Elina Floim
2022-03-31 05:40


x509: certificate relies on legacy Common Name field, use SANs or temporarily enable Common Name matching with GODEBUG=x509ignoreCN=0

This error indicates that the SSL certificate does not comply with the changes introduced in GoLang 1.15.

Since Go version 1.15, the deprecated, legacy behavior of treating the CommonName field on X.509 certificates as a hostname when no Subject Alternative Names (SAN) are present is now disabled by default. 

This may affect existing SSL certificates and any secure connection relying on these certificates, including databases, clients (such as Docker), and applications. 


A new valid certificate needs to be created to include the subjectAltName property, and should be added directly when creating an SSL self-signed certificate using openssl command, by specifying an -addext flag. For instance:

-addext "subjectAltName ="

(available from OpenSSL 1.1.1. More on this can be found on this StackExchange thread)

As a workaround, the behavior in which the CommonName field is being treated can be temporarily re-enabled by adding the value x509ignoreCN=0 to the GODEBUG environment variable. For instance, by running the following command in the terminal:

echo 'GODEBUG=x509ignoreCN=0' > ~/.profile

The certificate file can be then inspected to confirm that it contains the Subject Alternative Name:

openssl x509 -in server.crt -noout -text

Which output should include an entry similar to this:

X509v3 Subject Alternative

NOTE: Xray versions greater than 3.37 are bundled with an updated version of Go. Starting from Go version 1.18, the GODEBUG=x509ignoreCN=0 flag is deprecated, therefore, the certificates should be updated to overcome the error as the workaround will no longer be valid.