MySQL Error 2026: SSL Connection Error

MySQL client Error 2026 (HY000, CR_SSL_CONNECTION_ERROR) means the client library could not establish the requested SSL/TLS connection. The message includes a library-specific detail after SSL connection error:; capture that full text, because code 2026 alone does not identify whether the issue is certificate validation, TLS negotiation, or another client-side TLS failure. See the MySQL 8.4 client error reference.

Check the client TLS mode and certificate trust

Inspect the client or driver settings for ssl-mode, CA certificate paths, and TLS version restrictions. MySQL clients default to PREFERRED, which attempts encryption but can fall back to an unencrypted connection if TLS cannot be established. For a diagnostic test that requires TLS and verifies the server name, use the CA certificate supplied by your administrator:

mysql --host=db.example.com \
  --port=3306 \
  --user=app_user \
  --password \
  --ssl-ca=/path/to/ca.pem \
  --ssl-mode=VERIFY_IDENTITY

The client prompts for the password. VERIFY_CA checks the server certificate against the configured CA; VERIFY_IDENTITY also checks that the hostname used by the client matches the server certificate. If that test fails, verify that the CA file is current and trusted, the certificate is valid, and the application connects using a DNS name present in the certificate. MySQL’s automatically generated self-signed certificates do not provide a server name for VERIFY_IDENTITY; use a certificate configured for the server’s identity. Do not disable encryption or certificate verification as a blanket fix. See Configuring MySQL to use encrypted connections.

Compare TLS versions and ciphers on both sides

MySQL 8.4 supports TLS 1.2 and TLS 1.3; it does not support TLS 1.0 or TLS 1.1. TLS 1.3 requires both the server and client application to be built with OpenSSL 1.1.1 or higher. On the server, inspect the permitted versions with:

SHOW GLOBAL VARIABLES LIKE 'tls_version';

Also check the client’s --tls-version setting or the equivalent option in its connector. A connection requires at least one protocol and a compatible cipher permitted by both sides; an available TLS version may still fail if no compatible cipher is shared. Update an obsolete client or connector and align its TLS configuration with the server rather than re-enabling obsolete TLS versions. See MySQL TLS protocols and ciphers.

If the account requires a client certificate (REQUIRE X509, REQUIRE ISSUER, or REQUIRE SUBJECT), the client must also provide the required certificate and key. Ask the database administrator to confirm the account requirement; see the CREATE USER TLS options.

For X Protocol connections, check the X Plugin TLS configuration too. X Plugin can share the server’s TLS context or use separate mysqlx_ssl_* certificate and key settings. See Using encrypted connections with X Plugin.

Distinguish TLS errors from other connection failures

• Error 2026 (CR_SSL_CONNECTION_ERROR): the client library reports an SSL/TLS connection failure; inspect the complete detail after the code.
• Error 3159 (ER_SECURE_TRANSPORT_REQUIRED): the server rejected a nonsecure connection because require_secure_transport is enabled. Retry with a properly configured encrypted connection; do not turn off the server requirement to bypass it.
• Error 1043 (ER_HANDSHAKE_ERROR): the server reports a bad MySQL protocol handshake, which is not necessarily a TLS failure; see Error 1043 troubleshooting.
• Error 2003 (CR_CONN_HOST_ERROR): the client could not connect to the configured host and port; see Error 2003 troubleshooting.

For other authentication and connection codes, use the MySQL connection error triage helper or browse MySQL Error Troubleshooting.