What causes "table %s not found in vschema for keyspace %s" in vitessio/vitess?

Add the table (with appropriate vindex) to the target keyspace's vschema and re-apply it (vtctl ApplyVSchema)

table %s not found in vschema for keyspace %s

Error message

table %s not found in vschema for keyspace %s

What it means

buildMaterializer validates that every table in the workflow's TableSettings exists in the target keyspace's vschema. When the target keyspace is sharded, each target table must be declared in the target vschema (with a vindex) so rows can be routed. This error means a requested table is absent from the target vschema.

Source

Thrown at go/vt/vtctl/workflow/materializer.go:497

	return nil
}

func (mz *materializer) buildMaterializer() error {
	ctx := mz.ctx
	ms := mz.ms
	vschema, err := mz.ts.GetVSchema(ctx, ms.TargetKeyspace)
	if err != nil {
		return err
	}
	targetVSchema, err := vindexes.BuildKeyspaceSchema(vschema.Keyspace, ms.TargetKeyspace, mz.env.Parser())
	if err != nil {
		return err
	}
	if targetVSchema.Keyspace.Sharded {
		for _, ts := range ms.TableSettings {
			if targetVSchema.Tables[ts.TargetTable] == nil {
				return fmt.Errorf("table %s not found in vschema for keyspace %s", ts.TargetTable, ms.TargetKeyspace)
			}
		}
	}
	isPartial := false
	sourceShards, err := mz.sourceTs.GetServingShards(ctx, ms.SourceKeyspace)
	if err != nil {
		return err
	}
	if len(ms.SourceShards) > 0 {
		isPartial = true
		var sourceShards2 []*topo.ShardInfo
		for _, shard := range sourceShards {
			if slices.Contains(ms.SourceShards, shard.ShardName()) {
				sourceShards2 = append(sourceShards2, shard)
			}
		}
		sourceShards = sourceShards2
	}

View on GitHub (pinned to 01a25a7d17)

Solutions

Add the table (with appropriate vindex) to the target keyspace's vschema and re-apply it (vtctl ApplyVSchema)
Correct the table name in the workflow AddTables/CreateWorkflow request
Verify the workflow targets the intended keyspace and that the vschema was applied there

Example fix

// before (target vschema missing table)
{"sharded":true,"vindexes":{...},"tables":{}}
// after
{"sharded":true,"vindexes":{"hash":{"type":"hash"}},"tables":{"customer":{"column_vindexes":[{"column":"id","name":"hash"}]}}}

Defensive patterns

Strategy: validation

Validate before calling

vs, err := ts.GetVSchema(ctx, targetKeyspace)
if err != nil { return err }
for _, t := range tables {
    if vs.Tables[t] == nil {
        return fmt.Errorf("add table %s to target vschema for %s first", t, targetKeyspace)
    }
}

Try / catch

if err := workflowAddTables(ctx, ks, wf, tables); err != nil {
    if strings.Contains(err.Error(), "not found in vschema") {
        // apply an updated vschema including the table, then retry
    }
    return err
}

Prevention

Always ApplyVSchema on the target keyspace before creating MoveTables workflows
Keep target vschema in a checked-in file and apply it as part of workflow runbooks
Validate table names against the vschema in CI scripts before running vtctl

When it happens

Trigger: createWorkflowStreams or WorkflowAddTables calls buildMaterializer with ms.TableSettings referencing a table not present in targetVSchema.Tables while targetVSchema.Keyspace.Sharded is true.

Common situations: Adding a table to a MoveTables workflow before loading an updated vschema on the target keyspace; typo in table name; table created in MySQL but never added to the vschema JSON; vschema applied to wrong keyspace.

Related errors

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