vitessio/vitess · error

%v/%v has tables that are not in the vschema: %v

Error message

%v/%v has tables that are not in the vschema: %v

What it means

During ValidateVSchema, tables found on a shard's primary are compared against the keyspace's vschema. Any table present in the physical schema but absent from the vschema is collected into notFoundTables, and this error is recorded listing them. Internal operation tables are excluded from the check. This indicates the vschema (VTGate routing config) is out of sync with the actual database schema.

Source

Thrown at go/vt/wrangler/schema.go:164

				return
			}
			req := &tabletmanagerdatapb.GetSchemaRequest{ExcludeTables: excludeTables, IncludeViews: includeViews}
			primarySchema, err := schematools.GetSchema(ctx, wr.ts, wr.tmc, si.PrimaryAlias, req)
			if err != nil {
				shardFailures.RecordError(fmt.Errorf("GetSchema(%s, nil, %v, %v) (%v/%v) failed: %v", si.PrimaryAlias.String(),
					excludeTables, includeViews, keyspace, shard, err,
				))
				return
			}
			for _, tableDef := range primarySchema.TableDefinitions {
				if _, ok := vschm.Tables[tableDef.Name]; !ok {
					if !schema.IsInternalOperationTableName(tableDef.Name) {
						notFoundTables = append(notFoundTables, tableDef.Name)
					}
				}
			}
			if len(notFoundTables) > 0 {
				shardFailure := fmt.Errorf("%v/%v has tables that are not in the vschema: %v", keyspace, shard, notFoundTables)
				shardFailures.RecordError(shardFailure)
			}
		}(shard)
	}
	wg.Wait()
	if shardFailures.HasErrors() {
		return fmt.Errorf("ValidateVSchema(%v, %v, %v, %v) failed: %v", keyspace, shards, excludeTables, includeViews, shardFailures.Error().Error())
	}
	return nil
}

// PreflightSchema will try a schema change on the remote tablet.
func (wr *Wrangler) PreflightSchema(ctx context.Context, tabletAlias *topodatapb.TabletAlias, changes []string) ([]*tabletmanagerdatapb.SchemaChangeResult, error) {
	ti, err := wr.ts.GetTablet(ctx, tabletAlias)
	if err != nil {
		return nil, fmt.Errorf("GetTablet(%v) failed: %v", tabletAlias, err)
	}
	return wr.tmc.PreflightSchema(ctx, ti.Tablet, changes)

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Add the missing tables to the keyspace's vschema (vtctldclient ApplyVSchema with an updated JSON).
2. If a table is intentionally not managed by Vitess, add it to the vschema as an unsharded table entry or verify it's an internal operation table.
3. Re-run ValidateVSchema to confirm the vschema and physical schemas agree.
4. If the table is obsolete, drop it from MySQL or ignore via internal-operation-table handling.

Example fix

// before: vschema missing the table
{"tables": {"users": {}}}
// after: add the table reported by the error
{"tables": {"users": {}, "orders": {}}}

vschm, err := ts.GetVSchema(ctx, ks)
if err != nil { return err }
schema, err := schematools.GetSchema(ctx, ts, tmc, primaryAlias, req)
if err != nil { return err }
for _, td := range schema.TableDefinitions {
	if _, ok := vschm.Tables[td.Name]; !ok && !schema0.IsInternalOperationTableName(td.Name) {
		return fmt.Errorf("table %s missing from vschema", td.Name)
	}
}

if err := wr.ValidateVSchema(ctx, ks, shards, nil, nil, true); err != nil {
	if strings.Contains(err.Error(), "not in the vschema") {
		// parse missing tables from the message and apply an updated vschema
	}
}

When it happens

Trigger: Running ValidateVSchema where one or more tables exist in MySQL on a shard primary (e.g. created by a migration or manually) but have no corresponding entry in the keyspace's vschema (missing table vindex entries or table sections in the vschema JSON).

Common situations: Manual DDL applied directly to MySQL without updating the vschema; an online migration created new tables; vschema JSON was never updated after adding tables; new application tables added during development.

Related errors

• one or two tables must be specified
• at least one table must be specified
• table %v not found in vschema
• table %v not found in vschema
• keyspace %s not found in vschema

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