How to fix ERROR 2007: Protocol mismatch in MySQL

MySQLINTERMEDIATEHIGH

MySQL error 2007 (CR_VERSION_ERROR) occurs when the client and server use incompatible protocol versions or when connecting to the wrong port. This commonly happens with Docker port mapping errors or version mismatches between old clients and new servers. Fixing it requires checking port configuration and ensuring client/server version compatibility.

What this error means

MySQL error 2007 (CR_VERSION_ERROR) with the message "Protocol mismatch; server version = X, client version = Y" indicates that the client and server are unable to communicate using a compatible protocol version. This error has two main causes: version incompatibility between the MySQL client and server, or attempting to connect to the wrong port for the protocol being used. MySQL supports multiple protocols on different ports—the classic MySQL protocol runs on port 3306, while the X Protocol (used by MySQL Shell and Connectors) runs on port 33060 by default. The error is critical because it prevents any database connection from being established. The client cannot proceed with authentication or queries until the protocol versions match.

How to fix "ERROR 2007: Protocol mismatch"

1Verify the port you're connecting to

First, confirm you're using the correct port for your protocol. MySQL has two main endpoints:

- Classic MySQL protocol: port 3306 (mysql://, standard connections)
- X Protocol: port 33060 (mysqlx://, used by MySQL Shell and some connectors)

Check your connection string:

bash

# If using classic protocol, port should be 3306
mysql -h localhost -P 3306 -u user -p

# If using X Protocol, port should be 33060
mysql -h localhost -P 33060 -u user

If you're connecting to the wrong port, update your connection string or configuration file.

2Check your Docker port mapping (if using Docker)

If running MySQL in Docker, verify the port mapping is correct. The format is -p host_port:container_port.

Wrong (common mistake):

bash

docker run -d -p 3306:33060 mysql:latest
# This maps host port 3306 to container's X Protocol port 33060 - WRONG!

Correct:

bash

docker run -d -p 3306:3306 mysql:latest
# This maps host port 3306 to container's classic port 3306 - RIGHT!

Or in docker-compose.yml:

yaml

services:
  mysql:
    image: mysql:latest
    ports:
      - "3306:3306"  # Correct mapping
    environment:
      MYSQL_ROOT_PASSWORD: root

3Check client and server versions

Connect to the server (if possible) and verify both versions:

bash

# Check server version
mysql -h localhost -u root -p -e "SELECT VERSION();"

# Check client version
mysql --version

Look for major version differences. For example:
- Client: mysql Ver 8.0.35 (connecting to MySQL 5.7 server)
- Server: 5.7.42

If the major versions differ significantly, upgrade your client:

For MySQL 5.7:

bash

sudo apt-get install mysql-client-5.7

For MySQL 8.0+:

bash

sudo apt-get install mysql-client-8.0

Or update via Homebrew (macOS):

bash

brew install mysql-client
brew link --force mysql-client

4Upgrade MySQL client libraries (if needed)

If you're using an application or connector, update it to match or exceed your server version.

Node.js (mysql2 package):

bash

npm install mysql2@latest

Python (mysql-connector-python):

bash

pip install --upgrade mysql-connector-python

Java (MySQL Connector/J):

bash

# Update your pom.xml or build file to latest version
# Current: 8.0.35 or newer for MySQL 8.0+

PHP (mysqli or PDO):

bash

# Update PHP and MySQL extensions
sudo apt-get install php-mysql
# or
php -m | grep mysql

5Test with telnet or nc (port connectivity check)

Before troubleshooting further, verify the port is actually open and listening:

bash

# Using telnet (if installed)
telnet localhost 3306

# Using nc (netcat)
nc -zv localhost 3306

# Expected output: Connection successful

If the connection fails, the MySQL server may not be running or the port isn't exposed. Check:

bash

# Check if MySQL is running
sudo systemctl status mysql

# Start MySQL if stopped
sudo systemctl start mysql

# For Docker
docker ps | grep mysql

6Check for proxies, firewalls, or middleware

If you're connecting through a database proxy, connection pooler (PgBouncer, ProxySQL), or firewall, verify it's not corrupting the protocol:

bash

# Check if a proxy is running locally
netstat -tuln | grep 3306

# If multiple services on 3306, verify which is MySQL vs proxy
ss -tlnp | grep 3306

For ProxySQL or similar, ensure it's configured for the correct MySQL protocol and version:

ini

# In ProxySQL config
[mysql_servers]
hostgroup_id=0
hostname=192.168.1.100
port=3306
weight=1000
status=ONLINE
max_connections=200

7Update your application connection string

Once you've identified the correct port and version, update your application:

Connection string format:

bash

mysql://user:password@hostname:3306/database
# NOT
mysql://user:password@hostname:33060/database  # X Protocol port

Common configuration files:

bash

.env
DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=mypassword
DB_NAME=mydb

Docker environment variables:

bash

docker run -e DB_PORT=3306 myapp:latest

How to fix ERROR 2007: Protocol mismatch in MySQL

What this error means

Typical symptoms

Common causes

How to fix "ERROR 2007: Protocol mismatch"

Advanced notes

Related errors

Official resources & further reading