What causes "busy buffer" in go-sql-driver/mysql?

Use *sql.DB (pooled) instead of a shared single *sql.Conn for concurrent access.

busy buffer

Error message

busy buffer

What it means

ErrBusyBuffer is returned by the connection's internal write-buffer helpers (buffer.go:106,128,139 — takeBuffer/takeSmallBuffer/takeCompleteBuffer) when b.busy() is true. The buffer can only serve one outstanding write at a time, so this indicates two code paths tried to write on the same connection simultaneously.

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 03d76c7e07)

Solutions

Use *sql.DB (pooled) instead of a shared single *sql.Conn for concurrent access.
Serialize all operations on any single connection with a mutex if you must hold it.
Avoid setting aggressive per-query write timeouts that can overlap operations on a reused conn.
Treat the connection as bad after this error; discard it rather than reusing.

Example fix

// before: two goroutines share one conn
c, _ := db.Conn(ctx)
go c.ExecContext(ctx, q1) // -> ErrBusyBuffer
go c.ExecContext(ctx, q2)

// after: let the pool hand out separate conns
go db.ExecContext(ctx, q1)
go db.ExecContext(ctx, q2)
// or if exclusivity is required, guard c with a sync.Mutex

Defensive patterns

Strategy: validation

Validate before calling

// Never let two goroutines touch one conn. If exclusivity is required,
// guard it explicitly.
var mu sync.Mutex
mu.Lock(); defer mu.Unlock()
db.ExecContext(ctx, q) // serialized

Type guard

func isBusyBuffer(err error) bool {
    return errors.Is(err, mysql.ErrBusyBuffer)
}

Try / catch

if errors.Is(err, mysql.ErrBusyBuffer) {
    // concurrent write on one conn: stop sharing it; use db (pool) or a
    // mutex, and discard the poisoned conn.
}

Prevention

Prefer *sql.DB over hand-managed single connections for concurrent code.
Serialize any access to a long-lived *sql.Conn.
Avoid overlapping context-cancellation with new ops on a reused conn.

When it happens

Trigger: Concurrent writes to a single mysqlConn — e.g. sharing one *sql.Conn across goroutines, or a context-cancellation/timeout racing with an in-flight query write inside the driver. It is an internal-level error signalling connection misuse.

Common situations: Custom connection wrappers that bypass the pool; calling Exec/Query on a *sql.Conn from multiple goroutines; tight read/write timeouts that cancel a query mid-send while another starts.

Related errors

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