MySQL ERROR 2026 (HY000): SSL connection error when connecting from Django or the client
ERROR 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.
Fix it fast
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';"2Match what you see, then jump to its fix
- 1
SSL 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
Ssl_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
The same user connects fine with SSL switched offThe client default (PREFERRED) is failing and you need to see it without SSLFix
- 1
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.pem2Fix
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.pem3Verify
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
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/*.pem2Fix
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.pem3Verify
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
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=DISABLED2Fix
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 --checkConfirmed by mysqlclient.readthedocs.io
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
- ShopGoAn e-commerce aggregator with a Python scraping engine behind its catalog, past 10K Google Play downloads.
Related fixes
Databases
Installing the Airflow MySQL provider fails on pkg-config or mysqlclient
Building the mysqlclient wheel fails during the install
The Airflow MySQL provider depends on mysqlclient, which pip compiles against the MySQL C client library.
2 causes, each with a fixDatabases
Compiling a C or C++ program that includes mysql.h fails
undefined reference to `mysql_init'
The compiler only finds mysql.h when the MySQL client development files are installed and their folder is on the include path.
3 causes, each with a fixDatabases
An EC2 instance cannot reach its RDS database
Could not open connection to the host, on port <port>: Connect failed
RDS denies all access until a security group allows it.
3 causes, each with a fixDatabases
Locked out of a fresh MariaDB install as root on Mac or Linux
ERROR 1045 (28000): Access denied for user 'root'@'localhost' (using password: NO)
A fresh MariaDB root account is not a normal password account.
3 causes, each with a fixDatabases
An Aria table fails with 'Read page with wrong checksum' (error 1030, code 176)
ERROR 1030 (HY000): Got error 176 "Read page with wrong checksum" from storage engine Aria
Code 176 means MariaDB's Aria engine read a data or index page whose checksum does not match, so that table file is damaged.
3 causes, each with a fixDatabases
The client cannot open a TCP connection to MariaDB or MySQL (error 2003)
ERROR 2003 (HY000): Can't connect to MySQL server on '127.0.0.1:3306' (111)
Error 2003 means the client tried a TCP connection to the host and port and nobody answered.
4 causes, each with a fix