This error occurs when the MySQL client and server fail to complete the initial handshake process during connection establishment. It typically indicates authentication protocol mismatches, version incompatibility, or network configuration issues.
The CR_SERVER_HANDSHAKE_ERR (error code 2012) occurs during the connection phase when the MySQL client and server cannot successfully complete the handshake protocol. The handshake is the initial communication exchange that establishes authentication methods, protocol capabilities, and encryption parameters. When you attempt to connect to a MySQL server, the server first sends a handshake packet containing server version, authentication method, and capability flags. The client responds with its own capabilities and authentication credentials. If either side cannot understand the other's requirements, or if there's a mismatch in supported features, the handshake fails with error 2012. This error commonly surfaces when there are incompatibilities between client and server versions, particularly when newer clients connect to older servers using authentication plugins that weren't available in earlier MySQL versions. Network interruptions, firewall rules blocking protocol negotiation packets, or SSL/TLS configuration mismatches can also cause the handshake to fail.
Check the versions of both your MySQL client and server to identify compatibility issues:
# Check client version
mysql --version
# Check server version
mysql -h your-host -u your-user -p -e "SELECT VERSION();"If there's a significant version gap (e.g., MySQL 8.0 client connecting to MySQL 5.5 server), this is likely the root cause. Consider upgrading the older component or using a client version that matches the server.
Identify which authentication plugin the server is using and whether your client supports it:
-- Check default authentication plugin
SELECT @@default_authentication_plugin;
-- Check authentication plugin for your user
SELECT user, host, plugin FROM mysql.user WHERE user = 'your_username';If the server uses caching_sha2_password or sha256_password but your client only supports mysql_native_password, you'll need to either update the client or change the user's authentication method:
ALTER USER 'your_username'@'your_host' IDENTIFIED WITH mysql_native_password BY 'your_password';
FLUSH PRIVILEGES;If you're using SSL/TLS, temporarily disable it to determine if certificate issues are causing the handshake failure:
# Connect without SSL
mysql -h your-host -u your-user -p --skip-ssl
# Or specify to disable SSL explicitly
mysql -h your-host -u your-user -p --ssl-mode=DISABLEDIf this works, the issue is SSL-related. Verify your SSL certificates, check certificate expiration dates, and ensure the client trusts the server's CA certificate.
Verify that network devices are not interfering with MySQL handshake packets:
# Test basic connectivity to MySQL port (default 3306)
telnet your-host 3306
# Or using nc
nc -zv your-host 3306
# Check for packet filtering
tcpdump -i any -n port 3306Ensure your firewall allows bidirectional communication on the MySQL port, not just initial connection attempts. Some firewalls or proxies can corrupt protocol negotiation packets.
If using MySQL connectors in your application, update to the latest version that supports the server's authentication methods:
# For Python (MySQLdb/PyMySQL)
pip install --upgrade mysqlclient
# or
pip install --upgrade PyMySQL
# For Node.js
npm update mysql2
# For PHP, check php.ini for mysql extension version
php -i | grep mysqlRestart your application after updating client libraries to ensure the new versions are loaded.
If you've made configuration changes to the server's authentication settings, restart it to apply them:
# On systemd-based systems
sudo systemctl restart mysql
# On older systems
sudo service mysql restart
# Or using mysqladmin
mysqladmin -u root -p shutdown
mysqld_safe &After restarting, verify the server is listening and attempt the connection again.
Protocol Version Compatibility: The MySQL client/server protocol has evolved significantly between major versions. MySQL 8.0 introduced caching_sha2_password as the default authentication plugin, which is incompatible with clients designed for MySQL 5.x. If you must connect newer clients to older servers, you may need to explicitly downgrade the authentication method or use a legacy compatibility mode.
Known Bugs: MySQL bug #102275 documents a handshake failure when the server runs on IP addresses in the 10.0.x.x range in specific versions. Bug #91828 reports "bad handshake" errors introduced in MySQL 8.0.12. If you're affected by these, check the MySQL bug tracker for patches or workarounds.
Proxy and Load Balancer Considerations: If connecting through ProxySQL, HAProxy, or other database proxies, the handshake failure may occur at the proxy layer rather than the actual MySQL server. Check proxy logs and ensure the proxy supports the authentication methods in use.
SSH Tunneling: When using SSH tunnels with SSL connections, the double encryption can sometimes cause handshake issues. Try connecting through the tunnel without SSL, or use SSL only at the MySQL protocol level, not both tunnel and MySQL SSL.
EE_WRITE (3): Error writing file
How to fix "EE_WRITE (3): Error writing file" in MySQL
CR_PARAMS_NOT_BOUND (2031): No data supplied for parameters
How to fix "CR_PARAMS_NOT_BOUND (2031): No data supplied for parameters" in MySQL
CR_DNS_SRV_LOOKUP_FAILED (2070): DNS SRV lookup failed
How to fix "CR_DNS_SRV_LOOKUP_FAILED (2070): DNS SRV lookup failed" in MySQL
ERROR 1146: Table 'database.table' doesn't exist
How to fix "ERROR 1146: Table doesn't exist" in MySQL
ERROR 1040: Too many connections
How to fix "ERROR 1040: Too many connections" in MySQL