Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Databases and Redis

MySQL ERROR 2026 (HY000): SSL connection error when connecting from Django or the client

ErrorERROR 2026 (HY000): SSL connection error: <reason>

Short answer

Error 2026 means the client tried to set up an encrypted connection and the handshake failed. Check the error text after the colon, then see whether the server has SSL turned on. Fix it with a matching CA file, valid server certificates, or an explicit ssl-mode on the client, in that order of preference.

  • Applies to MySQL 8.4, mysqlclient 2.2, Django 5.2, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Ask the server whether it has encrypted connections on, and read the reason printed after 'SSL connection error:'. Run it from a login that works, for example over the local socket.

    mysql -u root -p -e "SHOW VARIABLES LIKE '%ssl%'; SHOW SESSION STATUS LIKE 'Ssl_cipher';"
  2. 2Match what you see, then jump to its fix

    1. 1SSL connection error: followed by a certificate verify or CA message, after you set ssl-mode=VERIFY_CA or VERIFY_IDENTITY or pass ssl_caThe client demands a CA file that does not match the server certificateFix
    2. 2Ssl_cipher is empty, and the account is created with REQUIRE SSL or the client uses ssl-mode=REQUIREDThe server has no valid certificate files, but the client or the account requires SSLFix
    3. 3The same user connects fine with SSL switched offThe client default (PREFERRED) is failing and you need to see it without SSLFix

What does the error look like?

  • ERROR 2026 (HY000): SSL connection error: <reason>
  • django.db.utils.OperationalError: (2026, 'SSL connection error: ...')

Cause 1 of 3

The client demands a CA file that does not match the server certificate

1Check

With VERIFY_CA the client checks the server certificate against the CA file you give it. That file must be the CA the server really uses. With VERIFY_IDENTITY the host name must also match the certificate, and certificates the server generates for itself do not carry the server name.

mysql -u app -p -h db.example.com --ssl-mode=VERIFY_CA --ssl-ca=/etc/ssl/mysql/ca.pem

2Fix

Copy the ca.pem from the server's data directory (or your own CA) to the client, and point ssl-ca at it, here through an option file that Django reads. If you use VERIFY_IDENTITY, issue a server certificate whose name matches the host you connect to.

DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.mysql",
        "OPTIONS": {"read_default_file": "/etc/myapp/my.cnf"},
    }
}

# /etc/myapp/my.cnf
[client]
ssl-mode = VERIFY_CA
ssl-ca = /etc/ssl/mysql/ca.pem

3Verify

Connect again and check that the connection is encrypted.

mysql -u app -p -h db.example.com --ssl-mode=VERIFY_CA --ssl-ca=/etc/ssl/mysql/ca.pem -e "SHOW SESSION STATUS LIKE 'Ssl_cipher';"

Confirmed by dev.mysql.com

Did this fix it?

Cause 2 of 3

The server has no valid certificate files, but the client or the account requires SSL

1Check

If no SSL options are set, the server looks for ca.pem, server-cert.pem and server-key.pem in its data directory. If it finds none it runs without encrypted connection support, and a client that requires SSL then fails.

sudo ls -l /var/lib/mysql/*.pem

2Fix

Install valid certificate files and set ssl-ca, ssl-cert and ssl-key in the server config, then restart. If the server is a private one and you cannot use SSL yet, connect without requiring it.

# /etc/mysql/mysql.conf.d/mysqld.cnf
[mysqld]
ssl-ca=/etc/mysql/certs/ca.pem
ssl-cert=/etc/mysql/certs/server-cert.pem
ssl-key=/etc/mysql/certs/server-key.pem

3Verify

Restart MySQL and confirm the server reports a cipher for a TCP connection.

sudo systemctl restart mysql
mysql -u app -p -h 127.0.0.1 -e "SHOW SESSION STATUS LIKE 'Ssl_cipher';"

Confirmed by dev.mysql.com

Did this fix it?

Cause 3 of 3

The client default (PREFERRED) is failing and you need to see it without SSL

1Check

Test with encryption disabled. If that works, the fault is in the TLS handshake and not in the account or password.

mysql -u app -p -h db.example.com --ssl-mode=DISABLED

2Fix

Use this only on a private network, as a stop-gap while you repair the certificates. In Django, pass ssl_mode through OPTIONS. The default PREFERRED does not protect against a man-in-the-middle, so move to VERIFY_CA once the CA file is right.

DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.mysql",
        "OPTIONS": {"ssl_mode": "DISABLED"},
    }
}

3Verify

Run a command that opens a connection.

python manage.py migrate --check

Confirmed by mysqlclient.readthedocs.io

Did this fix it?

How do I stop it coming back?

  • Keep one CA file under version control or in a secret store, and ship it to every client.
  • Renew server certificates before they expire and test the connection after each renewal.
  • Use VERIFY_CA or VERIFY_IDENTITY in production, not DISABLED.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.