go-sql-driver/mysql · critical

unsupported protocol version

Error message

unsupported protocol version %d. Version %d or higher is required

What it means

The server's initial handshake packet begins with a 1-byte protocol version; the driver requires >= 10 (minProtocolVersion). A lower version means an ancient or incompatible server that this driver cannot talk to.

Solutions

1. Connect to a modern MySQL or MariaDB server, which all speak protocol version 10.
2. Verify the host/port actually point at a MySQL/MariaDB server (e.g. with a mysql CLI or telnet).
3. Upgrade or replace the incompatible server.

Example fix

null

// Before relying on the connection, ping to confirm a compatible server.
if err := db.Ping(); err != nil {
    return fmt.Errorf("cannot reach compatible MySQL server: %w", err)
}

null

// The error surfaces at connect/Ping time.
db, err := sql.Open("mysql", dsn)
if err == nil {
    err = db.Ping()
}
if err != nil {
    return err
}

When it happens

Trigger: Connecting to a pre-protocol-10 server (pre-MySQL 3.x) or to a non-MySQL service that happens to listen on port 3306 and emits a different protocol version byte.

Common situations: Pointing the driver at the wrong host/port (another service); a very old embedded MySQL fork; misconfigured port forwarding.

Related errors

• unknown field type
• protocol error, illegal decimals value
• argument count mismatch
• can't convert %T to time.Time
• cannot convert type: %T

AI-assisted analysis of go-sql-driver/mysql@03d76c7e07 (2026-08-07). Data as JSON: /api/errors/8af64579bab14a5d. Report an issue: GitHub.

Appendix: source

Thrown at packets.go:197

******************************************************************************/

// Handshake Initialization Packet
// https://dev.mysql.com/doc/dev/mysql-server/latest/page_protocol_connection_phase_packets_protocol_handshake_v10.html
// https://mariadb.com/kb/en/connection/#initial-handshake-packet
func (mc *mysqlConn) readHandshakePacket() (data []byte, capabilities capabilityFlag, extendedCapabilities extendedCapabilityFlag, plugin string, err error) {
	data, err = mc.readPacket()
	if err != nil {
		return
	}

	if data[0] == iERR {
		err = mc.handleErrorPacket(data)
		return
	}

	// protocol version [1 byte]
	if data[0] < minProtocolVersion {
		return nil, 0, 0, "", fmt.Errorf(
			"unsupported protocol version %d. Version %d or higher is required",
			data[0],
			minProtocolVersion,
		)
	}

	// server version [null terminated string]
	// connection id [4 bytes]
	pos := 1 + bytes.IndexByte(data[1:], 0x00) + 1 + 4

	// first part of the password cipher [8 bytes]
	authData := data[pos : pos+8]

	// (filler) always 0x00 [1 byte]
	pos += 8 + 1

	// capability flags (lower 2 bytes) [2 bytes]
	capabilities = capabilityFlag(binary.LittleEndian.Uint16(data[pos : pos+2]))

View on GitHub (pinned to 03d76c7e07)