this user requires clear text authentication. If you still…

Error message

this user requires clear text authentication. If you still want to use it, please add 'allowCleartextPasswords=1' to your DSN

What it means

ErrCleartextPassword is returned from auth() (auth.go:298) when the server requires the mysql_clear_password plugin but the DSN did not opt in with allowCleartextPasswords=1. The plugin sends the password in cleartext, so the driver requires explicit consent; it should only be enabled over TLS or a unix socket.

Solutions

Add allowCleartextPasswords=1 to the DSN AND ensure the transport is encrypted (tls=true or unix socket) before enabling it.
If using AWS RDS IAM, generate the IAM token as the password and connect over TLS with allowCleartextPasswords=1.
Alternatively change the user's auth plugin to mysql_native_password / caching_sha2_password so cleartext is unnecessary.
Never enable this option on a plaintext TCP link.

Example fix

// before
dsn := "user:token@tcp(db.x.amazonaws.com:3306)/db?tls=true"
// -> ErrCleartextPassword (IAM auth uses mysql_clear_password)

// after
dsn := "user:token@tcp(db.x.amazonaws.com:3306)/db?tls=true&allowCleartextPasswords=1"

Defensive patterns

Strategy: validation

Validate before calling

// For cleartext-plugin accounts, build the DSN with the explicit opt-in
// and require an encrypted transport alongside it.
requiresClearPlugin := true
dsn := "user:pass@tcp(host:3306)/db?tls=true"
if requiresClearPlugin {
    dsn += "&allowCleartextPasswords=1"
}

Type guard

func requiresCleartextOptIn(err error) bool {
    return errors.Is(err, mysql.ErrCleartextPassword)
}

Try / catch

if err := db.PingContext(ctx); errors.Is(err, mysql.ErrCleartextPassword) {
    // server/user needs mysql_clear_password; enable the flag (over TLS!)
    // and retry, or change the account's auth plugin.
}

Prevention

Only enable allowCleartextPasswords together with tls=true or a unix socket.
For AWS RDS IAM, generate the token per-connection and pass it as the password.
Prefer caching_sha2_password / mysql_native_password where the server allows it.
Never transmit allowCleartextPasswords traffic over plain TCP.

When it happens

Trigger: Authenticating as a user whose account uses mysql_clear_password (AWS Aurora/RDS IAM auth, PAM plugin, MySQL Enterprise Audit) while allowCleartextPasswords is false (the default).

Common situations: Switching to AWS RDS IAM token auth; enabling the PAM authentication plugin; pointing an existing DSN at a server whose accounts were migrated to cleartext auth.

Understand the failure class

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

Related errors

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

Appendix: source

Thrown at errors.go:22

//
// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this file,
// 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))

View on GitHub (pinned to 03d76c7e07)