How to fix ERROR 2007: Protocol mismatch in MySQL

MySQLINTERMEDIATEHIGHUpdated Dec 25, 2025· 209 views

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.

Quick fix

Fixes 2007

# 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
  1. Verify the port you're connecting to
  2. Check your Docker port mapping (if using Docker)
  3. Check client and server versions
  4. Upgrade MySQL client libraries (if needed)
mysql — error
# 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
ERROR 2007: Protocol mismatch

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.

Typical symptoms

  • Connection fails immediately with 'ERROR 2007' or 'Protocol mismatch' message
  • MySQL client or application cannot connect to the database
  • Docker containers fail to connect to MySQL with 'Protocol mismatch'
  • HeidiSQL, DBeaver, or other clients disconnect during connection
  • Error mentions specific version numbers like 'server version = 11, client version = 10'
  • X Protocol clients fail to connect to classic MySQL port
  • Database migration or upgrade breaks all client connections

Common causes

  1. Client and server have incompatible MySQL versions (old client connecting to new server or vice versa)
  2. Connecting to the wrong port for the protocol (e.g., X Protocol port 33060 instead of classic port 3306)
  3. Docker port mapping misconfiguration (e.g., mapping 3306:33060 instead of 3306:3306)
  4. MySQL client library version doesn't support server protocol (especially with MySQL 5.7 to 8.0 upgrades)
  5. Middleware, proxy, or load balancer performing incorrect protocol translation
  6. Server upgraded to MySQL 8.0+ but clients still use legacy MySQL 5.7 libraries
  7. Connection pooler or connector configured for wrong protocol version

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

Advanced notes

X Protocol vs Classic Protocol:

MySQL 8.0+ introduced the X Protocol alongside the traditional MySQL protocol. They run on different ports and require different client libraries:

- Classic MySQL Protocol (port 3306): Used by mysql CLI, mysql2/promise, PDO, JDBC
- X Protocol (port 33060): Used by MySQL Shell, MySQL Connectors, and some ORMs like Prisma (optional)

Attempting to use a classic client on the X Protocol port will always fail with error 2007.

Version Compatibility:

MySQL maintains backward compatibility for 1-2 minor versions, but major version jumps (e.g., 5.7 → 8.0 or 8.0 → 9.0) may require client updates. The protocol changes between major versions are usually transparent to applications, but the underlying libraries may not support deprecated features.

Docker Networking:

In Docker Compose, services communicate via hostname (service name), not localhost. Correct configuration:

yaml
app:
  image: myapp:latest
  links:
    - mysql:db
mysql:
  image: mysql:latest
  ports:
    - "3306:3306"

Connection string from app: mysql://root:password@db:3306/mydb

SSL/TLS Connections:

If using SSL, ensure both client and server support the same TLS version. MySQL 8.0.28+ requires TLS 1.2+. A TLS version mismatch can sometimes manifest as a protocol error.

Frequently asked questions

What does "2007" mean?
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.
How do I fix "2007"?
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 causes "2007"?
Client and server have incompatible MySQL versions (old client connecting to new server or vice versa) Connecting to the wrong port for the protocol (e.g., X Protocol port 33060 instead of classic port 3306) Docker port mapping misconfiguration (e.g., mapping 3306:33060 instead of 3306:3306)
Is the "2007" 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