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

Error message

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

What it means

ErrPktTooLarge is returned by writePacket (packets.go:128-129) when the data to be sent exceeds mc.maxAllowedPacket, the value negotiated from the server's max_allowed_packet. This protects against the server rejecting an oversized packet; the driver fails fast on the client side. The message points at Config.MaxAllowedPacket.

Source

Thrown at errors.go:30

	"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.
type NopLogger struct{}

View on GitHub (pinned to c426bd9379)

Solutions

Raise max_allowed_packet on the MySQL server (my.cnf + SET GLOBAL) AND set maxAllowedPacket in the DSN to match: `?maxAllowedPacket=67108864`.
Chunk the data: batch INSERTs into smaller groups, or stream large blobs in pieces.
Reduce per-statement size (e.g. split a giant IN list into multiple queries).

Example fix

// before
db.Exec("INSERT INTO t(b) VALUES(?)", hugeBlob) // > maxAllowedPacket
// after
// server: set global max_allowed_packet = 256*1024*1024;
dsn := "u:p@tcp(host:3306)/db?maxAllowedPacket=268435456"
// and/or split the blob into chunked writes

Defensive patterns

Strategy: validation

Validate before calling

max := len(serializedPayload)
if int64(max) > int64(cfg.MaxAllowedPacket) {
    return fmt.Errorf("payload %d exceeds maxAllowedPacket %d", max, cfg.MaxAllowedPacket)
}

Type guard

func withinLimit(size, max int64) bool { return size <= max }

Try / catch

if errors.Is(err, mysql.ErrPktTooLarge) {
    // split the batch and retry in smaller chunks
}

Prevention

Match DSN maxAllowedPacket to the server's max_allowed_packet.
Batch large writes in bounded sizes.
Stream or chunk large BLOBs.

When it happens

Trigger: Issuing a query/Exec whose serialized payload (query text + parameters/binds) is larger than maxAllowedPacket. The check at packets.go:127 `if pktLen > mc.maxAllowedPacket` triggers. Common with bulk INSERTs, large BLOB/TEXT writes, or huge IN(...) lists.

Common situations: Bulk-loading large rows; inserting big binary blobs; generating huge single statements from code; default max_allowed_packet (often 4MB or 64MB) too small for the workload; DSN maxAllowedPacket not matching the server.

Related errors

AI-assisted analysis of go-sql-driver/mysql@c426bd9379 (2026-08-04). Data as JSON: /data/errors/660d817bbf64f6b6.json. Report an issue: GitHub.