NET::ERR_CERT_COMMON_NAME_INVALID - Error Message

Resolving NET::ERR_CERT_COMMON_NAME_INVALID in Flask Applications

Understand and troubleshoot the NET::ERR_CERT_COMMON_NAME_INVALID error when developing or deploying Flask applications, focusing on certificate configuration and browser trust.

The NET::ERR_CERT_COMMON_NAME_INVALID error is a common browser security warning that indicates a mismatch between the hostname you are trying to access and the hostname listed in the SSL/TLS certificate presented by the server. While often encountered in production environments, it can also surface during local development with Flask, especially when using self-signed certificates or misconfigured proxies. This article will guide you through understanding the root causes and provide practical solutions for Flask applications.

Understanding the Common Name (CN) Mismatch

Every SSL/TLS certificate contains information about the identity of the server it secures. A crucial piece of this information is the Common Name (CN) or, more commonly in modern certificates, the Subject Alternative Name (SAN) field. When your browser attempts to establish a secure connection (HTTPS) with a server, it performs a check:

1. Hostname Extraction: The browser extracts the hostname from the URL you're trying to visit (e.g., localhost, 127.0.0.1, my-app.com).
2. Certificate Retrieval: The server presents its SSL/TLS certificate.
3. Name Matching: The browser compares the extracted hostname with the CN and SAN entries in the certificate.

If there's no match, the browser throws the NET::ERR_CERT_COMMON_NAME_INVALID error, indicating that it cannot verify the server's identity for the requested hostname. This is a security measure to prevent man-in-the-middle attacks.

flowchart TD
    A[User Navigates to HTTPS URL] --> B{Browser Extracts Hostname}
    B --> C[Server Presents SSL/TLS Certificate]
    C --> D{Browser Checks Certificate CN/SAN}
    D -- Hostname Matches --> E[Secure Connection Established]
    D -- Hostname Mismatch --> F["NET::ERR_CERT_COMMON_NAME_INVALID"]
    F --> G[Connection Blocked / Warning Displayed]

Flowchart of browser certificate validation process.

Common Scenarios and Solutions in Flask

This error typically arises in a few key scenarios when working with Flask. Addressing these scenarios involves either correctly generating certificates or configuring your development environment to trust them.

Scenario 1: Self-Signed Certificates for Local Development

When you generate a self-signed certificate for local Flask development, you must ensure that the Common Name (CN) or Subject Alternative Name (SAN) in the certificate matches the hostname you use to access your application (e.g., localhost, 127.0.0.1, or a custom domain like myflaskapp.local).

# Generate a self-signed certificate with OpenSSL
# For 'localhost'
openssl req -x509 -newkey rsa:4096 -nodes -keyout key.pem -out cert.pem -days 365 \
    -subj "/CN=localhost" -addext "subjectAltName=DNS:localhost,IP:127.0.0.1"

# For a custom local domain (e.g., myflaskapp.local)
# Make sure 'myflaskapp.local' resolves to 127.0.0.1 in your hosts file
openssl req -x509 -newkey rsa:4096 -nodes -keyout key.pem -out cert.pem -days 365 \
    -subj "/CN=myflaskapp.local" -addext "subjectAltName=DNS:myflaskapp.local,IP:127.0.0.1"

Generating self-signed certificates with OpenSSL for localhost or a custom domain.

After generating the certificate, you need to configure your Flask application to use it. You also need to explicitly trust this self-signed certificate in your browser or operating system's certificate store. Without trusting it, the browser will still show the error because it doesn't recognize the certificate authority.

from flask import Flask

app = Flask(__name__)

@app.route('/')
def hello():
    return 'Hello, HTTPS Flask!'

if __name__ == '__main__':
    # Ensure key.pem and cert.pem are in the same directory
    app.run(ssl_context=('cert.pem', 'key.pem'), host='0.0.0.0', port=5000)

Running a Flask app with SSL context.

Scenario 2: Accessing by IP Address Instead of Hostname

If your certificate was issued for a specific hostname (e.g., myflaskapp.com) but you try to access the application using its IP address (e.g., https://192.168.1.100), you will encounter this error. The certificate's CN/SAN will not match the IP address.

To resolve this, always access your Flask application using the hostname for which the certificate was issued. If you absolutely need to access it via IP, you must regenerate the certificate to include the IP address in the SAN field, as shown in the OpenSSL example above (IP:127.0.0.1).

Scenario 3: Reverse Proxies (Nginx, Apache) and Flask

When deploying Flask behind a reverse proxy like Nginx or Apache, the SSL termination often happens at the proxy level. This means the proxy handles the HTTPS connection with the client, and then communicates with Flask over plain HTTP (or internal HTTPS). The certificate error typically occurs if the proxy's certificate is misconfigured or if the client is trying to connect directly to Flask over HTTPS without the correct certificate.

server {
    listen 443 ssl;
    server_name myflaskapp.com;

    ssl_certificate /etc/nginx/ssl/myflaskapp.com.crt;
    ssl_certificate_key /etc/nginx/ssl/myflaskapp.com.key;

    location / {
        proxy_pass http://127.0.0.1:5000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Example Nginx configuration for SSL termination with Flask backend.

In this setup, ensure that the server_name in your Nginx configuration matches the Common Name or Subject Alternative Name of your myflaskapp.com.crt certificate. The client browser only sees the certificate presented by Nginx, not by Flask directly. Flask itself can run without SSL in this scenario.

1. Verify Certificate Details

Use openssl x509 -in cert.pem -text -noout to inspect your certificate's Common Name (CN) and Subject Alternative Name (SAN) fields. Ensure they match the hostname you are using.

2. Check Hostname Resolution

For local development, ensure your /etc/hosts (Linux/macOS) or C:\Windows\System32\drivers\etc\hosts (Windows) file correctly maps your custom domain (e.g., myflaskapp.local) to 127.0.0.1.

3. Trust Self-Signed Certificates

If using self-signed certificates, import them into your operating system's trusted root certificate store. This is a one-time step per certificate for local development.

4. Clear Browser Cache

Sometimes, browsers cache old certificate information. Clear your browser's SSL state or cache to ensure it fetches the latest certificate.