vitessio/vitess · error

unknown tableID %v in UpdateRows event

Error message

unknown tableID %v in UpdateRows event

What it means

binlog streamer error: an UpdateRows event references a tableID that was never seen via a preceding TableMap event, so row images cannot be decoded. Usually caused by starting the stream mid-events or a missed/filtered TableMap.

Source

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

			})

			rows, err := ev.Rows(format, tce.tm)
			if err != nil {
				return pos, err
			}

			statements = bls.appendInserts(statements, tce, &rows)

			if autocommit {
				if err = commit(ev.Timestamp()); err != nil {
					return pos, err
				}
			}
		case ev.IsUpdateRows():
			tableID := ev.TableID(format)
			tce, ok := tableMaps[tableID]
			if !ok {
				return pos, fmt.Errorf("unknown tableID %v in UpdateRows event", tableID)
			}
			if tce.ti == nil {
				// Skip cross-db statements.
				continue
			}
			setTimestamp := &binlogdatapb.BinlogTransaction_Statement{
				Category: binlogdatapb.BinlogTransaction_Statement_BL_SET,
				Sql:      fmt.Appendf(nil, "SET TIMESTAMP=%d", ev.Timestamp()),
			}
			statements = append(statements, FullBinlogStatement{
				Statement: setTimestamp,
			})

			rows, err := ev.Rows(format, tce.tm)
			if err != nil {
				return pos, err
			}

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Restart the stream from a transaction boundary before the offending update
2. Run mysqlbinlog on the source file to confirm the TABLE_MAP exists and is intact
3. Ensure db/stream filters do not exclude TABLE_MAP events
4. Check event decoding (format description) matches the MySQL version that wrote the log

// confirm pairing before streaming:
// mysqlbinlog --start-position=<pos> <file> | grep -E 'Table_map|Update_rows'

err := streamer.Stream(ctx, signals)
if err != nil && strings.Contains(err.Error(), "unknown tableID") {
    // restart from a transaction boundary preceding the update
}

When it happens

Trigger: ev.IsUpdateRows() returns a tableID absent from tableMaps in parseEvents — missing/skipped preceding TABLE_MAP_EVENT, corrupt stream, or event misalignment.

Common situations: Mid-transaction stream start, relay log corruption, external tools manipulating binlogs, or a filtered stream that dropped the table map while keeping update-rows events.

Related errors

• unknown tableID %v in WriteRows event
• unknown tableID %v in DeleteRows event
• unknown table %v in schema
• [%v] cached columns count[%d] mismatch binglog row [%d]
• GetPreviousGTIDs: previous GTIDs not found

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