How to fix CR_SERVER_HANDSHAKE_ERR (2012): Error in server handshake in MySQL

MySQLINTERMEDIATEHIGHUpdated Dec 22, 2025· 159 views

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.

Quick fix

Fixes CR_SERVER_HANDSHAKE_ERR (2012): Error in server handshake

# Check client version
mysql --version

# Check server version
mysql -h your-host -u your-user -p -e "SELECT VERSION();"
  1. Verify MySQL client and server versions
  2. Check the server authentication plugin
  3. Test connection without SSL first
  4. Check firewall and network connectivity
mysql — error
# Check client version
mysql --version
# Check server version
mysql -h your-host -u your-user -p -e "SELECT VERSION();"
CR_SERVER_HANDSHAKE_ERR (2012): Error in server handshake

What this error means

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.

Typical symptoms

  • Connection attempts fail immediately with "Error in server handshake" message
  • Applications cannot establish database connections despite correct credentials
  • MySQL client tools report error code 2012 when connecting
  • Connections work with older client versions but fail with newer ones
  • Error occurs only when connecting from specific network locations or IP addresses

Common causes

  1. Client and server are running incompatible MySQL versions with different protocol capabilities
  2. Server requires an authentication plugin (like caching_sha2_password) that the client does not support
  3. Network firewall or proxy is interfering with handshake packets between client and server
  4. SSL/TLS certificate mismatch or expired certificates when secure connections are required
  5. Server default authentication plugin differs from what the client expects
  6. Client capabilities flag does not match server requirements for the authentication method
  7. Server is running on an IP address range that triggers handshake bugs (e.g., 10.0.x.x in older versions)

How to fix "CR_SERVER_HANDSHAKE_ERR (2012): Error in server handshake"

1Verify MySQL client and server versions

Check the versions of both your MySQL client and server to identify compatibility issues:

bash
# 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.

2Check the server authentication plugin

Identify which authentication plugin the server is using and whether your client supports it:

sql
-- 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:

sql
ALTER USER 'your_username'@'your_host' IDENTIFIED WITH mysql_native_password BY 'your_password';
FLUSH PRIVILEGES;
3Test connection without SSL first

If you're using SSL/TLS, temporarily disable it to determine if certificate issues are causing the handshake failure:

bash
# 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=DISABLED

If 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.

4Check firewall and network connectivity

Verify that network devices are not interfering with MySQL handshake packets:

bash
# 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 3306

Ensure your firewall allows bidirectional communication on the MySQL port, not just initial connection attempts. Some firewalls or proxies can corrupt protocol negotiation packets.

5Update MySQL client libraries

If using MySQL connectors in your application, update to the latest version that supports the server's authentication methods:

bash
# 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 mysql

Restart your application after updating client libraries to ensure the new versions are loaded.

6Restart the MySQL server

If you've made configuration changes to the server's authentication settings, restart it to apply them:

bash
# 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.

Advanced notes

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.

Frequently asked questions

What does "CR_SERVER_HANDSHAKE_ERR (2012): Error in server handshake" mean?
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.
How do I fix "CR_SERVER_HANDSHAKE_ERR (2012): Error in server handshake"?
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.
What causes "CR_SERVER_HANDSHAKE_ERR (2012): Error in server handshake"?
Client and server are running incompatible MySQL versions with different protocol capabilities Server requires an authentication plugin (like caching_sha2_password) that the client does not support Network firewall or proxy is interfering with handshake packets between client and server
Is the "CR_SERVER_HANDSHAKE_ERR (2012): Error in server handshake" error serious?
Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Official resources & further reading