vitessio/vitess · error

unknown table %v in schema

Error message

unknown table %v in schema

What it means

A TABLE_MAP_EVENT references a table that is not present in the cached schema (bls.se). The streamer must know the table's columns/PKs to render rows, so when the table-map lookup returns nil TableInfo it aborts the stream.

Source

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

			// TODO(alainjobart) if table is already in map,
			// just use it.

			tce := &tableCacheEntry{
				tm:              tm,
				keyspaceIDIndex: -1,
			}
			tableMaps[tableID] = tce

			// Check we're in the right database, and if so, fill
			// in more data.
			if tm.Database != "" && tm.Database != bls.cp.DBName() {
				continue
			}

			// Find and fill in the table schema.
			tce.ti = bls.se.GetTable(sqlparser.NewIdentifierCS(tm.Name))
			if tce.ti == nil {
				return pos, fmt.Errorf("unknown table %v in schema", tm.Name)
			}

			// Fill in the resolver if needed.
			if bls.resolverFactory != nil {
				tce.keyspaceIDIndex, tce.resolver, err = bls.resolverFactory(tce.ti)
				if err != nil {
					return pos, fmt.Errorf("cannot find column to use to find keyspace_id for table %v", tm.Name)
				}
			}

			// Fill in PK indexes if necessary.
			if bls.extractPK {
				tce.pkNames = make([]*querypb.Field, len(tce.ti.PKColumns))
				tce.pkIndexes = make([]int, len(tce.ti.Fields))
				for i := range tce.pkIndexes {
					// Put -1 as default in here.
					tce.pkIndexes[i] = -1
				}

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Reload/refresh the schema engine's cache so the table is present (re-run the stream or trigger schema reload)
2. Verify the table exists in the source database and that the streamer's db name/keyspace filter matches
3. If the table was intentionally dropped, restart the stream from a position after the DROP so the event is skipped
4. Check that the streamer was not started with a restricted/blind schema that omits needed tables

ti := schemaEngine.GetTable(sqlparser.NewIdentifierCS(tableName))
if ti == nil {
    return fmt.Errorf("table %s missing from schema cache before streaming", tableName)
}

err := streamer.Stream(ctx, signals)
if err != nil && strings.Contains(err.Error(), "unknown table") {
    // trigger schema reload, then restart stream
}

When it happens

Trigger: Row-based binlog contains rows for a table missing from the streamer's schema cache: the table was dropped mid-stream, the streamer was started with an incomplete/blind schema (Schema Engine returned no entry), or the database name in the event differs from what the schema engine loaded.

Common situations: Schema changed (DROP TABLE / RENAME) while vreplication was running; streamer pointed at a keyspace/db whose schema wasn't fully loaded; using a custom schema with missing tables; stale schema cache after ALTERs.

Related errors

• unknown tableID %v in WriteRows event
• unknown tableID %v in UpdateRows event
• unknown tableID %v in DeleteRows event
• [%v] cached columns count[%d] mismatch binglog row [%d]
• not allowed: deny-all security-policy enforced

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