vitessio/vitess · critical

failed to set @source_binlog_checksum=@@global.binlog_checks

Error message

failed to set @source_binlog_checksum=@@global.binlog_checksum: %v

What it means

NewBinlogConnection issues "SET @source_binlog_checksum = @@global.binlog_checksum, @master_binlog_checksum=@@global.binlog_checksum" right after connecting to a MySQL server for replication. This tells the server the client understands checksummed binlog events. If that statement fails, the connection is discarded and this error is returned, because replication without negotiating checksum support can produce corrupt event streams.

Source

Thrown at go/vt/binlog/binlog_connection.go:98

	return bc, nil
}

// ServerID returns the server ID used by this binlog connection.
func (bc *BinlogConnection) ServerID() uint32 {
	return bc.serverID
}

// connectForReplication create a MySQL connection ready to use for replication.
func connectForReplication(cp dbconfigs.Connector) (*mysql.Conn, error) {
	ctx := context.Background()
	conn, err := cp.Connect(ctx)
	if err != nil {
		return nil, err
	}
	// Tell the server that we understand the format of events
	// that will be used if binlog_checksum is enabled on the server.
	if _, err := conn.ExecuteFetch("SET @source_binlog_checksum = @@global.binlog_checksum, @master_binlog_checksum=@@global.binlog_checksum", 0, false); err != nil {
		return nil, fmt.Errorf("failed to set @source_binlog_checksum=@@global.binlog_checksum: %v", err)
	}

	return conn, nil
}

// StartBinlogDumpFromCurrent requests a replication binlog dump from
// the current position.
func (bc *BinlogConnection) StartBinlogDumpFromCurrent(ctx context.Context) (replication.Position, <-chan mysql.BinlogEvent, <-chan error, error) {
	ctx, bc.cancel = context.WithCancel(ctx)

	position, err := bc.PrimaryPosition()
	if err != nil {
		return replication.Position{}, nil, nil, fmt.Errorf("failed to get primary position: %v", err)
	}

	c, e, err := bc.StartBinlogDumpFromPosition(ctx, "", position)
	return position, c, e, err
}

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Check the wrapped %v detail: if it is "server has gone away" or a connection error, verify network stability and MySQL uptime, then retry the connection.
2. Verify the replication user can execute the SET and read @@global.binlog_checksum.
3. Confirm the target server's flavor/version supports binlog_checksum; for MariaDB use the appropriate flavor handling.
4. Ensure any proxy/firewall between Vitess and MySQL does not kill connections immediately after handshake.

Example fix

// before: assumes any failure is transient
conn, err := binlog.NewBinlogConnection(cp)
// after: inspect and retry on connection-class errors
conn, err := binlog.NewBinlogConnection(cp)
if err != nil {
	if mysql.IsConnErr(err) {
		// backoff and retry dialing the primary
	}
	log.Error("binlog connect failed", slog.Any("error", err))
}

// preflight: verify the primary is reachable and checksums are readable
conn, err := mysql.Connect(ctx, cp)
if err != nil {
	return fmt.Errorf("primary unreachable before binlog connect: %w", err)
}
qr, err := conn.ExecuteFetch("SELECT @@global.binlog_checksum", 1, false)
conn.Close()
if err != nil || len(qr.Rows) == 0 {
	return fmt.Errorf("cannot read binlog_checksum on primary: %w", err)
}

conn, err := binlog.NewBinlogConnection(cp)
if err != nil {
	if strings.Contains(err.Error(), "failed to set @source_binlog_checksum") || mysql.IsConnErr(err) {
		// exponential backoff, then retry NewBinlogConnection
	}
	return err
}

When it happens

Trigger: Opening a binlog connection (NewBinlogConnection) to a MySQL/MariaDB server whose @@global.binlog_checksum cannot be read or whose session rejects the SET — network drop between connect and SET, server going away, or replication user lacking permissions.

Common situations: MySQL server restarted or crashed mid-connect; connection closed by idle timeout or firewall between dial and SET; MariaDB or very old MySQL flavor quirks around binlog_checksum variables; replication user with restricted privileges.

Related errors

• failed to send the ComBinlogDump command: %v
• GetPreviousGTIDs: previous GTIDs not found
• startPos.GTIDSet is wrong type - expected filePosGTID, got:
• failed to get primary position: %v
• failed to SHOW BINARY LOGS: %v

AI-assisted analysis of vitessio/vitess@01a25a7d17 (2026-09-01). Data as JSON: /api/errors/4e4fbf9bc2fa333a. Report an issue: GitHub.