{"record":{"id":"882ba59dfaf6ddfa","repo":"vitessio/vitess","slug":"got-a-real-event-before-format-description-event-882ba5","errorCode":null,"errorMessage":"got a real event before FORMAT_DESCRIPTION_EVENT: %#v","messagePattern":"got a real event before FORMAT_DESCRIPTION_EVENT: %#v","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"go/vt/vttablet/tabletserver/vstreamer/vstreamer.go","lineNumber":548,"sourceCode":"\t\tvar err error\n\t\tvs.format, err = ev.Format()\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"can't parse FORMAT_DESCRIPTION_EVENT: %v, event data: %#v\", err, ev)\n\t\t}\n\t\tvs.eventGTID = nil\n\t\treturn nil, nil\n\t}\n\n\t// We can't parse anything until we get a FORMAT_DESCRIPTION_EVENT that\n\t// tells us the size of the event header.\n\tif vs.format.IsZero() {\n\t\t// The only thing that should come before the FORMAT_DESCRIPTION_EVENT\n\t\t// is a fake ROTATE_EVENT, which the primary sends to tell us the name\n\t\t// of the current log file.\n\t\tif ev.IsRotate() {\n\t\t\treturn nil, nil\n\t\t}\n\t\treturn nil, fmt.Errorf(\"got a real event before FORMAT_DESCRIPTION_EVENT: %#v\", ev)\n\t}\n\n\t// Strip the checksum, if any. We don't actually verify the checksum, so discard it.\n\tev, _, err := ev.StripChecksum(vs.format)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"can't strip checksum from binlog event: %v, event data: %#v\", err, ev)\n\t}\n\n\tshouldSend := func(evType binlogdatapb.VEventType) bool {\n\t\tif vs.eventTypesToStream != nil && !vs.eventTypesToStream[evType] {\n\t\t\treturn false\n\t\t}\n\t\treturn true\n\t}\n\n\ttimeNowUnixNano := time.Now().UnixNano()\n\tvar vevents []*binlogdatapb.VEvent\n\tswitch {","sourceCodeStart":530,"sourceCodeEnd":566,"githubUrl":"https://github.com/vitessio/vitess/blob/01a25a7d176f94613b8d59d799f438380a8760e4/go/vt/vttablet/tabletserver/vstreamer/vstreamer.go#L530-L566","documentation":"vstreamer refuses to parse any binlog event that arrives before the FORMAT_DESCRIPTION_EVENT. Only a fake ROTATE_EVENT (sent by the primary to announce the current log file name) is legal before it, because the FORMAT_DESCRIPTION_EVENT establishes the event format (including checksum layout) needed to decode everything else. Any other event at that point means the stream is malformed or mis-sequenced.","triggerScenarios":"parseEvent receives a real event (not a ROTATE_EVENT) while vs.format is still unset, i.e. before the server has sent the FORMAT_DESCRIPTION_EVENT on the binlog connection.","commonSituations":"Streaming from a server whose binlog stream starts mid-file without a format description; a replication bug or middleware/proxy that drops or reorders the initial events; resuming from a bad starting position on the binlog file.","solutions":["Verify the starting GTID/position points to a valid point in a binlog file where a FORMAT_DESCRIPTION_EVENT precedes your position","Restart the VStream from the beginning of a binlog file or from a known-good GTID","Check for proxies/binlog filters between Vitess and MySQL that may strip the FORMAT_DESCRIPTION_EVENT","Confirm the primary's binlog files are intact (mysqlbinlog the file at that position)"],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// Before streaming, sanity check the binlog file at the start position:\n// mysqlbinlog --start-position=<pos> <logfile> | head\n// The first event must be FORMAT_DESCRIPTION_EVENT (or a fake ROTATE).","typeGuard":null,"tryCatchPattern":"err := streamErr\nif strings.Contains(err.Error(), \"got a real event before FORMAT_DESCRIPTION_EVENT\") {\n    // restart the vstream from the beginning of the binlog file / valid GTID\n}","preventionTips":["Always start streams at file-beginning positions or valid GTIDs","Keep binlog files intact and avoid intermediaries that reorder events","Monitor for failovers that change binlog file naming mid-stream"],"tags":["binlog","replication","vstreamer","stream-ordering"],"backgroundTag":"binlog-stream-out-of-order","analyzedSha":"01a25a7d176f94613b8d59d799f438380a8760e4","analyzedAt":"2026-09-01T17:28:30.605Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}