vitessio/vitess · error

can't parse FORMAT_DESCRIPTION_EVENT: %v, event data: %#v

Error message

can't parse FORMAT_DESCRIPTION_EVENT: %v, event data: %#v

What it means

When a FORMAT_DESCRIPTION_EVENT arrives, parseEvents calls ev.Format() to learn the binlog format (header size, checksum settings, etc.). If that decode fails, the event data cannot be interpreted and the stream aborts. The error includes both the parse error and a dump of the raw event.

Source

Thrown at go/vt/binlog/binlog_streamer.go:323

		case err = <-errs:
			return pos, err
		case <-ctx.Done():
			log.Info("stopping early due to binlog Streamer service shutdown or client disconnect")
			return pos, ctx.Err()
		}

		// Validate the buffer before reading fields from it.
		if !ev.IsValid() {
			return pos, fmt.Errorf("can't parse binlog event, invalid data: %#v", ev)
		}

		// We need to keep checking for FORMAT_DESCRIPTION_EVENT even after we've
		// seen one, because another one might come along (e.g. on log rotate due to
		// binlog settings change) that changes the format.
		if ev.IsFormatDescription() {
			format, err = ev.Format()
			if err != nil {
				return pos, fmt.Errorf("can't parse FORMAT_DESCRIPTION_EVENT: %v, event data: %#v", err, ev)
			}
			continue
		}

		// We can't parse anything until we get a FORMAT_DESCRIPTION_EVENT that
		// tells us the size of the event header.
		if format.IsZero() {
			// The only thing that should come before the FORMAT_DESCRIPTION_EVENT
			// is a fake ROTATE_EVENT, which the primary sends to tell us the name
			// of the current log file.
			if ev.IsRotate() {
				continue
			}
			return pos, fmt.Errorf("got a real event before FORMAT_DESCRIPTION_EVENT: %#v", ev)
		}

		// Strip the checksum, if any. We don't actually verify the checksum, so discard it.
		ev, _, err = ev.StripChecksum(format)

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Confirm the MySQL server version is supported by Vitess's binlog parser
2. Run mysqlbinlog on the file to see if it is readable/corrupt
3. Restore the binlog from a replica or restart the stream from a position on an intact log file
4. If a version change introduced this, upgrade Vitess to a release supporting that server's binlog format

if err := streamer.Stream(ctx); err != nil {
	if strings.Contains(err.Error(), "FORMAT_DESCRIPTION_EVENT") {
		// unsupported/corrupt format: check server version and binlog integrity
	}
}

When it happens

Trigger: During Stream/parseEvents, ev.IsFormatDescription() is true but ev.Format() returns an error — typically a format-description buffer that is shorter or longer than the expected layout for the server's binlog version.

Common situations: Binlog produced by an unsupported MySQL/MariaDB version whose FORMAT_DESCRIPTION_EVENT layout differs; corrupted binlog file; replaying mixed-version binlogs during an upgrade.

Related errors

• can't parse binlog event, invalid data: %#v
• can't get GTID from binlog event: %v, event data: %#v
• can't parse INTVAR_EVENT: %v, event data: %#v
• ParseBinlogCoordinates: Cannot parse BinlogCoordinates from
• ParseBinlogCoordinates: invalid pos: %s

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