{"record":{"id":"4e4fbf9bc2fa333a","repo":"vitessio/vitess","slug":"failed-to-set-source-binlog-checksum-global-bin","errorCode":null,"errorMessage":"failed to set @source_binlog_checksum=@@global.binlog_checksum: %v","messagePattern":"failed to set @source_binlog_checksum=@@global\\.binlog_checksum: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"go/vt/binlog/binlog_connection.go","lineNumber":98,"sourceCode":"\treturn bc, nil\n}\n\n// ServerID returns the server ID used by this binlog connection.\nfunc (bc *BinlogConnection) ServerID() uint32 {\n\treturn bc.serverID\n}\n\n// connectForReplication create a MySQL connection ready to use for replication.\nfunc connectForReplication(cp dbconfigs.Connector) (*mysql.Conn, error) {\n\tctx := context.Background()\n\tconn, err := cp.Connect(ctx)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\t// Tell the server that we understand the format of events\n\t// that will be used if binlog_checksum is enabled on the server.\n\tif _, err := conn.ExecuteFetch(\"SET @source_binlog_checksum = @@global.binlog_checksum, @master_binlog_checksum=@@global.binlog_checksum\", 0, false); err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to set @source_binlog_checksum=@@global.binlog_checksum: %v\", err)\n\t}\n\n\treturn conn, nil\n}\n\n// StartBinlogDumpFromCurrent requests a replication binlog dump from\n// the current position.\nfunc (bc *BinlogConnection) StartBinlogDumpFromCurrent(ctx context.Context) (replication.Position, <-chan mysql.BinlogEvent, <-chan error, error) {\n\tctx, bc.cancel = context.WithCancel(ctx)\n\n\tposition, err := bc.PrimaryPosition()\n\tif err != nil {\n\t\treturn replication.Position{}, nil, nil, fmt.Errorf(\"failed to get primary position: %v\", err)\n\t}\n\n\tc, e, err := bc.StartBinlogDumpFromPosition(ctx, \"\", position)\n\treturn position, c, e, err\n}","sourceCodeStart":80,"sourceCodeEnd":116,"githubUrl":"https://github.com/vitessio/vitess/blob/01a25a7d176f94613b8d59d799f438380a8760e4/go/vt/binlog/binlog_connection.go#L80-L116","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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.","Verify the replication user can execute the SET and read @@global.binlog_checksum.","Confirm the target server's flavor/version supports binlog_checksum; for MariaDB use the appropriate flavor handling.","Ensure any proxy/firewall between Vitess and MySQL does not kill connections immediately after handshake."],"exampleFix":"// before: assumes any failure is transient\nconn, err := binlog.NewBinlogConnection(cp)\n// after: inspect and retry on connection-class errors\nconn, err := binlog.NewBinlogConnection(cp)\nif err != nil {\n\tif mysql.IsConnErr(err) {\n\t\t// backoff and retry dialing the primary\n\t}\n\tlog.Error(\"binlog connect failed\", slog.Any(\"error\", err))\n}","handlingStrategy":"retry","validationCode":"// preflight: verify the primary is reachable and checksums are readable\nconn, err := mysql.Connect(ctx, cp)\nif err != nil {\n\treturn fmt.Errorf(\"primary unreachable before binlog connect: %w\", err)\n}\nqr, err := conn.ExecuteFetch(\"SELECT @@global.binlog_checksum\", 1, false)\nconn.Close()\nif err != nil || len(qr.Rows) == 0 {\n\treturn fmt.Errorf(\"cannot read binlog_checksum on primary: %w\", err)\n}","typeGuard":null,"tryCatchPattern":"conn, err := binlog.NewBinlogConnection(cp)\nif err != nil {\n\tif strings.Contains(err.Error(), \"failed to set @source_binlog_checksum\") || mysql.IsConnErr(err) {\n\t\t// exponential backoff, then retry NewBinlogConnection\n\t}\n\treturn err\n}","preventionTips":["Monitor primary health/reachability before starting replication streams.","Grant the replication user privileges to read global variables and run the SET.","Avoid proxies that kill shortly-after-handshake connections; test through the full network path.","Keep MySQL and Vitess flavors/versions aligned for binlog_checksum support."],"tags":["mysql","replication","binlog","network"],"backgroundTag":"binlog-handshake-failed","analyzedSha":"01a25a7d176f94613b8d59d799f438380a8760e4","analyzedAt":"2026-09-01T17:28:30.605Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}