{"record":{"id":"61e17940aa6a4d82","repo":"go-sql-driver/mysql","slug":"this-user-requires-clear-text-authentication-if-y","errorCode":null,"errorMessage":"this user requires clear text authentication. If you still want to use it, please add 'allowCleartextPasswords=1' to your DSN","messagePattern":"this user requires clear text authentication\\. If you still want to use it, please add 'allowCleartextPasswords=1' to your DSN","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"errors.go","lineNumber":22,"sourceCode":"//\n// This Source Code Form is subject to the terms of the Mozilla Public\n// License, v. 2.0. If a copy of the MPL was not distributed with this file,\n// You can obtain one at http://mozilla.org/MPL/2.0/.\n\npackage 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))","sourceCodeStart":4,"sourceCodeEnd":40,"githubUrl":"https://github.com/go-sql-driver/mysql/blob/03d76c7e07908e255ce62d126d07ede3f2365d86/errors.go#L4-L40","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","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."],"exampleFix":"// before\ndsn := \"user:token@tcp(db.x.amazonaws.com:3306)/db?tls=true\"\n// -> ErrCleartextPassword (IAM auth uses mysql_clear_password)\n\n// after\ndsn := \"user:token@tcp(db.x.amazonaws.com:3306)/db?tls=true&allowCleartextPasswords=1\"","handlingStrategy":"validation","validationCode":"// For cleartext-plugin accounts, build the DSN with the explicit opt-in\n// and require an encrypted transport alongside it.\nrequiresClearPlugin := true\ndsn := \"user:pass@tcp(host:3306)/db?tls=true\"\nif requiresClearPlugin {\n    dsn += \"&allowCleartextPasswords=1\"\n}","typeGuard":"func requiresCleartextOptIn(err error) bool {\n    return errors.Is(err, mysql.ErrCleartextPassword)\n}","tryCatchPattern":"if err := db.PingContext(ctx); errors.Is(err, mysql.ErrCleartextPassword) {\n    // server/user needs mysql_clear_password; enable the flag (over TLS!)\n    // and retry, or change the account's auth plugin.\n}","preventionTips":["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."],"tags":["authentication","security","config"],"backgroundTag":null,"analyzedSha":"03d76c7e07908e255ce62d126d07ede3f2365d86","analyzedAt":"2026-08-07T10:39:17.340Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}