packet for query is too large. Try adjusting the…

Error message

packet for query is too large. Try adjusting the `Config.MaxAllowedPacket`

What it means

ErrPktTooLarge is returned from writePacket (packets.go:129) when the payload length (len(data)-4) exceeds mc.maxAllowedPacket before anything is written. mc.maxAllowedPacket comes from Config.MaxAllowedPacket (default 64 MiB, const.go:17) or the server's max_allowed_packet system variable read at connect (connector.go:180).

Solutions

Raise max_allowed_packet on the server (SET GLOBAL max_allowed_packet=...) and restart/for new conns.
Set Config.MaxAllowedPacket / DSN maxAllowedPacket to match so the client cap agrees with the server.
Chunk the work: page the IN-list, batch INSERTs into smaller statements, or stream via LOAD DATA LOCAL INFILE.
Prefer prepared statements + chunked parameters over one giant interpolated query.

Example fix

// before: one giant interpolated INSERT -> ErrPktTooLarge
q := "INSERT INTO t(v) VALUES " + strings.Join(values, ",") // too big

// after: batch in chunks the server can accept
dsn := "...&maxAllowedPacket=67108864"
const batch = 1000
for i := 0; i < len(values); i += batch {
    end := min(i+batch, len(values))
    q := "INSERT INTO t(v) VALUES " + strings.Join(values[i:end], ",")
    db.Exec(q)
}

Defensive patterns

Strategy: validation

Validate before calling

// Bound your payloads against the negotiated limit before sending.
const maxPkt = 64 << 20 // keep in sync with server max_allowed_packet
if len(blob) > maxPkt-1024 {
    return fmt.Errorf("payload %d exceeds max_allowed_packet", len(blob))
}

Type guard

func isPktTooLarge(err error) bool {
    return errors.Is(err, mysql.ErrPktTooLarge)
}

Try / catch

if errors.Is(err, mysql.ErrPktTooLarge) {
    // either raise server + client max_allowed_packet, or chunk the work.
}

Prevention

Keep Config.MaxAllowedPacket aligned with the server's max_allowed_packet.
Batch large INSERTs and IN-lists into page-sized chunks.
Prefer prepared statements over one huge interpolated query.
Use LOAD DATA LOCAL INFILE for bulk loads instead of giant packets.

When it happens

Trigger: Sending a single statement, prepared-parameter, or COM_QUERY whose serialized size exceeds max_allowed_packet — e.g. a huge IN(...) list, a very large bound []byte/string parameter, or a multi-row bulk INSERT in one statement.

Common situations: Bulk-loading large blobs; generating INSERT ... VALUES with thousands of rows; a query string built by string concatenation growing past the limit.

Related errors

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

Appendix: source

Thrown at errors.go:29

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 {
	Print(v ...any)
}

// NopLogger is a nop implementation of the Logger interface.

View on GitHub (pinned to 03d76c7e07)