{"id":"deab31a352e8a60b","repo":"go-sql-driver/mysql","slug":"mysql-server-does-not-support-required-protocol-41","errorCode":null,"errorMessage":"MySQL server does not support required protocol 41+","messagePattern":"MySQL server does not support required protocol 41\\+","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"errors.go","lineNumber":27,"sourceCode":"package mysql\n\nimport (\n\t\"errors\"\n\t\"fmt\"\n\t\"log\"\n\t\"os\"\n)\n\n// Various errors the driver might return. Can change between driver versions.\nvar (\n\tErrInvalidConn       = errors.New(\"invalid connection\")\n\tErrMalformPkt        = errors.New(\"malformed packet\")\n\tErrNoTLS             = errors.New(\"TLS requested but server does not support TLS\")\n\tErrCleartextPassword = errors.New(\"this user requires clear text authentication. If you still want to use it, please add 'allowCleartextPasswords=1' to your DSN\")\n\tErrNativePassword    = errors.New(\"this user requires mysql native password authentication\")\n\tErrOldPassword       = 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\")\n\tErrUnknownPlugin     = errors.New(\"this authentication plugin is not supported\")\n\tErrOldProtocol       = errors.New(\"MySQL server does not support required protocol 41+\")\n\tErrPktSync           = errors.New(\"commands out of sync. You can't run this command now\")\n\tErrPktSyncMul        = errors.New(\"commands out of sync. Did you run multiple statements at once?\")\n\tErrPktTooLarge       = errors.New(\"packet for query is too large. Try adjusting the `Config.MaxAllowedPacket`\")\n\tErrBusyBuffer        = errors.New(\"busy buffer\")\n\n\t// errBadConnNoWrite is used for connection errors where nothing was sent to the database yet.\n\t// If this happens first in a function starting a database interaction, it should be replaced by driver.ErrBadConn\n\t// to trigger a resend. Use mc.markBadConn(err) to do this.\n\t// See https://github.com/go-sql-driver/mysql/pull/302\n\terrBadConnNoWrite = errors.New(\"bad connection\")\n)\n\nvar defaultLogger = Logger(log.New(os.Stderr, \"[mysql] \", log.Ldate|log.Ltime))\n\n// Logger is used to log critical error messages.\ntype Logger interface {\n\tPrint(v ...any)\n}","sourceCodeStart":9,"sourceCodeEnd":45,"githubUrl":"https://github.com/go-sql-driver/mysql/blob/c426bd93799de0f0e094c8f0582872c529d0ed0a/errors.go#L9-L45","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Run a supported MySQL/MariaDB version (5.7+ recommended; 4.1 is the absolute floor).","Confirm the address/port actually points at a MySQL server and not another service returning garbage.","If a legacy server is unavoidable, find an archived driver version that supported the old protocol — not recommended."],"exampleFix":"// before\n// target is MySQL 4.0 -> handshake fails\nsql.Open(\"mysql\", \"u:p@tcp(host:3306)/db\")\n// after\n// run MySQL 5.7/8.x on the host, then the same call succeeds","handlingStrategy":"validation","validationCode":"// Ensure the target is a supported server before connecting:\n// mysql --version  -> must be >= 4.1 (ideally 5.7+)\nif serverMajor < 5 { return errors.New(\"unsupported server version\") }","typeGuard":null,"tryCatchPattern":"if errors.Is(err, mysql.ErrOldProtocol) {\n    // the target is not a supported MySQL server; do not retry blindly\n}","preventionTips":["Run supported MySQL/MariaDB versions.","Verify the host/port is actually MySQL.","Reject ancient servers during deployment validation."],"tags":["protocol","legacy","compatibility"],"analyzedSha":"c426bd93799de0f0e094c8f0582872c529d0ed0a","analyzedAt":"2026-08-04T21:52:59.219Z","schemaVersion":2}