go-sql-driver/mysql · error

this authentication plugin is not supported

Error message

this authentication plugin is not supported

What it means

ErrUnknownPlugin is returned from auth() (auth.go:342) when the server's negotiated authentication plugin is not one the driver implements (caching_sha2_password, mysql_native_password, mysql_old_password, mysql_clear_password, sha256_password, client_ed25519). The unknown plugin name is logged before the error is returned.

Solutions

1. Upgrade go-sql-driver/mysql to a version that supports the plugin the server is requesting.
2. Change the account's auth plugin to one the driver supports (e.g. caching_sha2_password or mysql_native_password).
3. Check the driver log line ("unknown auth plugin: <name>") to identify exactly which plugin is missing.
4. For MariaDB ed25519, ensure you are on a driver version with client_ed25519 support.

Example fix

// before: older driver, server account uses a plugin the driver lacks
//   auth switch -> "unknown auth plugin: auth_pam_compat"

// after: modernize the account to a supported plugin
//   ALTER USER 'user'@'%' IDENTIFIED WITH 'caching_sha2_password' BY 'pass';
// and/or upgrade the module:
//   go get github.com/go-sql-driver/mysql@latest

// Before relying on a connection, probe the account's plugin so you can
// fail fast with a clear message instead of a generic auth error.
// (Run once per environment against an admin connection.)
//   SELECT plugin FROM mysql.user WHERE user='app';

func isUnknownPlugin(err error) bool {
    return errors.Is(err, mysql.ErrUnknownPlugin)
}

if errors.Is(err, mysql.ErrUnknownPlugin) {
    // log includes "unknown auth plugin: <name>"; upgrade the driver or
    // change the account to a supported plugin, then retry.
}

When it happens

Trigger: An auth-switch request from the server to a plugin the driver has no handler for, or an initial handshake advertising an exotic/proprietary plugin; also when a newer server defaults to a plugin added after this driver version.

Common situations: Connecting to a server using a custom or commercial auth plugin; running an older driver against a newer server that introduced a new default plugin; MariaDB ed25519 accounts without client_ed25519 support compiled/enabled.

Understand the failure class

• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

• this user requires mysql native password authentication
• invalid max_allowed_packet value
• this user requires clear text authentication. If you still…
• this user requires old password authentication. If you…
• invalid compressed packet: uncompressed length in header is

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

Appendix: source

Thrown at errors.go:25

// You can obtain one at http://mozilla.org/MPL/2.0/.

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 {

View on GitHub (pinned to 03d76c7e07)