go-sql-driver/mysql · critical

MySQL server does not support required protocol 41+

Error message

MySQL server does not support required protocol 41+

What it means

ErrOldProtocol is returned during handshake (packets.go:217) when the server's capability flags do not include clientProtocol41, i.e. the server speaks the pre-4.1 client/server protocol. The driver implements only protocol version 41 and above, so any older server is rejected outright.

Source

Thrown at errors.go:27

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 c426bd9379)

Solutions

  1. Run a supported MySQL/MariaDB version (5.7+ recommended; 4.1 is the absolute floor).
  2. Confirm the address/port actually points at a MySQL server and not another service returning garbage.
  3. If a legacy server is unavoidable, find an archived driver version that supported the old protocol — not recommended.

Example fix

// before
// target is MySQL 4.0 -> handshake fails
sql.Open("mysql", "u:p@tcp(host:3306)/db")
// after
// run MySQL 5.7/8.x on the host, then the same call succeeds
Defensive patterns

Strategy: validation

Validate before calling

// Ensure the target is a supported server before connecting:
// mysql --version  -> must be >= 4.1 (ideally 5.7+)
if serverMajor < 5 { return errors.New("unsupported server version") }

Try / catch

if errors.Is(err, mysql.ErrOldProtocol) {
    // the target is not a supported MySQL server; do not retry blindly
}

Prevention

When it happens

Trigger: Connecting to a MySQL server older than 4.1 (released ~2003). The handshake reader at packets.go:216 checks capabilities & clientProtocol41 == 0 and returns the error. Any operation that establishes a connection (sql.Open + first query) triggers the handshake.

Common situations: Ancient embedded MySQL; unmaintained appliances; accidentally pointing at a stub/mock server that does not implement the protocol; a misbehaving proxy that returns a non-MySQL handshake packet.

Related errors

AI-assisted analysis of go-sql-driver/mysql@c426bd9379 (2026-08-04). Data as JSON: /data/errors/deab31a352e8a60b.json. Report an issue: GitHub.