commands out of sync. Did you run multiple statements at onc

Error message

commands out of sync. Did you run multiple statements at once?

What it means

ErrPktSyncMul is returned by readPacket (packets.go:74) when a sequence-number mismatch is detected while assembling a large (multi-part, >16MB) packet. Because the payload spans several packets, a desync mid-stream means the reassembled data would be corrupt, so the connection is closed and this sentinel returned.

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 c426bd9379)

Solutions

Avoid sharing a connection across goroutines; drain and close rows/result sets properly.
If multiStatements is enabled, iterate every result with rows.NextResultSet() until false.
Page large reads so responses stay under a single packet, or rule out a corrupting intermediary (load balancer, sidecar).

Example fix

// before
db.QueryContext(ctx, "SELECT ...; SELECT ...", ) // multiStatements, results not drained
// after
rows, _ := db.QueryContext(ctx, q)
for rows.Next() { ... }
for rows.NextResultSet() {
    for rows.Next() { ... }
}
rows.Close()

Defensive patterns

Strategy: try-catch

Validate before calling

// If multiStatements=true, always drain all result sets:
for rows.NextResultSet() { for rows.Next() {} }

Try / catch

if errors.Is(err, mysql.ErrPktSyncMul) {
    // large-packet desync; connection is closed, surface and reconnect
}

Prevention

Disable multiStatements unless you fully drain results.
Page large reads to stay under one packet.
Rule out a corrupting intermediary.

When it happens

Trigger: A query whose response exceeds maxPacketSize (16 MiB) is split across packets; if a sequence number is wrong mid-assembly (packets.go:72, prevData already non-empty), readPacket closes the connection and returns ErrPktSyncMul. Often co-occurs with multiStatements=1 results read incorrectly, or with a proxy corrupting large streams.

Common situations: Selecting very large rows/LOBs through a buggy proxy; using multiStatements and not iterating all result sets; concurrent access producing interleaved packets on a shared connection.

Related errors

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