go-sql-driver/mysql · error

MySQL server does not support required protocol 41+

Error message

MySQL server does not support required protocol 41+

What it means

ErrOldProtocol is returned from readHandshakePacket (packets.go:217) when the server's capability flags lack clientProtocol41. The driver mandates the 4.1+ protocol (protocol version 10, const.go:18) and will not negotiate the legacy wire format.

Solutions

1. Upgrade the server to MySQL/MariaDB 4.1 or newer (anything from the last ~20 years).
2. Verify the address actually points at a MySQL server and not another protocol on that port.
3. If a legacy server is unavoidable, use an older client stack that still speaks the pre-41 protocol.

Example fix

// before
//   mysqld 4.0.x -> ErrOldProtocol on every connect

// after: run a supported server version (5.7 / 8.0 / MariaDB 10.x+)
//   the handshake advertises clientProtocol41 and the error disappears

// Sanity-check the server version during provisioning so a pre-4.1 server
// is caught before the app tries to connect.
//   SELECT VERSION();  -- must be >= 4.1 / protocol 10

func isOldProtocol(err error) bool {
    return errors.Is(err, mysql.ErrOldProtocol)
}

if errors.Is(err, mysql.ErrOldProtocol) {
    // not fixable client-side: upgrade the server or retarget the DSN.
}

When it happens

Trigger: Connecting to a MySQL server older than 4.1 whose handshake does not advertise the protocol-41 capability bit; effectively unreachable with any modern client.

Common situations: Embedded systems or ancient appliances bundling MySQL 3.x/4.0; misdirected DSN pointing at a non-MySQL service that returns a pre-41-style handshake.

Related errors

• invalid max_allowed_packet value
• commands out of sync. Did you run multiple statements at…
• commands out of sync. You can't run this command now
• invalid compressed packet: uncompressed length in header is
• no pem data found, data

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

Appendix: source

Thrown at errors.go:26

package mysql

import (
	"errors"
	"fmt"
	"log"
	"os"
)

// Various errors the driver might return. Can change between driver versions.
var (
	ErrInvalidConn       = errors.New("invalid connection")
	ErrMalformPkt        = errors.New("malformed packet")
	ErrNoTLS             = errors.New("TLS requested but server does not support TLS")
	ErrCleartextPassword = errors.New("this user requires clear text authentication. If you still want to use it, please add 'allowCleartextPasswords=1' to your DSN")
	ErrNativePassword    = errors.New("this user requires mysql native password authentication")
	ErrOldPassword       = errors.New("this user requires old password authentication. If you still want to use it, please add 'allowOldPasswords=1' to your DSN. See also https://github.com/go-sql-driver/mysql/wiki/old_passwords")
	ErrUnknownPlugin     = errors.New("this authentication plugin is not supported")
	ErrOldProtocol       = errors.New("MySQL server does not support required protocol 41+")
	ErrPktSync           = errors.New("commands out of sync. You can't run this command now")
	ErrPktSyncMul        = errors.New("commands out of sync. Did you run multiple statements at once?")
	ErrPktTooLarge       = errors.New("packet for query is too large. Try adjusting the `Config.MaxAllowedPacket`")
	ErrBusyBuffer        = errors.New("busy buffer")

	// errBadConnNoWrite is used for connection errors where nothing was sent to the database yet.
	// If this happens first in a function starting a database interaction, it should be replaced by driver.ErrBadConn
	// to trigger a resend. Use mc.markBadConn(err) to do this.
	// See https://github.com/go-sql-driver/mysql/pull/302
	errBadConnNoWrite = errors.New("bad connection")
)

var defaultLogger = Logger(log.New(os.Stderr, "[mysql] ", log.Ldate|log.Ltime))

// Logger is used to log critical error messages.
type Logger interface {
	Print(v ...any)

View on GitHub (pinned to 03d76c7e07)