{"id":"971c60aee1b56f67","repo":"go-sql-driver/mysql","slug":"invalid-connection","errorCode":null,"errorMessage":"invalid connection","messagePattern":"invalid connection","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"errors.go","lineNumber":20,"sourceCode":"//\n// Copyright 2013 The Go-MySQL-Driver Authors. All rights reserved.\n//\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)","sourceCodeStart":2,"sourceCodeEnd":38,"githubUrl":"https://github.com/go-sql-driver/mysql/blob/c426bd93799de0f0e094c8f0582872c529d0ed0a/errors.go#L2-L38","documentation":"ErrInvalidConn is a sentinel returned whenever a connection is deemed unusable. It is produced in readPacket (packets.go:59, :88, :101) when a network read fails or a malformed zero-length packet arrives, and in transaction.go/connection.go when operating on a connection that is already bad. The underlying I/O cause is logged via mc.log but NOT wrapped into the sentinel, so callers see only this generic error.","triggerScenarios":"Any read on a connection whose TCP socket is broken: the header read at packets.go:52 fails, or the body read at packets.go:94 fails, or a zero-length packet arrives without prior data (packets.go:83-88). Also returned by Begin/Commit/Rollback on a connection whose mc.bad flag is set (transaction.go:17,33), and by Ping (connection.go:202).","commonSituations":"MySQL server or a load balancer (e.g. AWS RDS proxy, ProxySQL) closed an idle connection; network partition; server restart; exceeding wait_timeout; firewall dropping long-lived connections.","solutions":["Configure the connection pool to recycle connections before the server/network does: db.SetConnMaxLifetime(...) shorter than the server's wait_timeout, and set db.SetMaxIdleConns / SetMaxOpenConns appropriately.","Retry idempotent operations; database/sql will retry on driver.ErrBadConn, so ensure you are not catching the error and suppressing the retry.","Verify the MySQL server is reachable and not OOM-killed / restarting; check network stability between client and host."],"exampleFix":"// before\ndb.SetConnMaxLifetime(0) // connections live forever, server kills them\n// after\ndb.SetConnMaxLifetime(5 * time.Minute) // recycle before server wait_timeout\ndb.SetMaxIdleConns(10)","handlingStrategy":"retry","validationCode":"db.SetConnMaxLifetime(min(serverWaitTimeout, 5*time.Minute))\ndb.SetMaxIdleConns(8)","typeGuard":"func isBadConn(err error) bool { return errors.Is(err, mysql.ErrInvalidConn) }","tryCatchPattern":"var lastErr error\nfor attempt := 0; attempt < 3; attempt++ {\n    err := fn()\n    if err == nil { return nil }\n    if !errors.Is(err, mysql.ErrInvalidConn) { return err }\n    lastErr = err\n}\nreturn lastErr","preventionTips":["Set ConnMaxLifetime below the server's wait_timeout.","Let database/sql retry by returning driver.ErrBadConn from wrappers.","Monitor for connection churn and server restarts."],"tags":["network","connection","sentinel"],"analyzedSha":"c426bd93799de0f0e094c8f0582872c529d0ed0a","analyzedAt":"2026-08-04T21:52:59.219Z","schemaVersion":2}