vitessio/vitess · error

vindex %s not found in vschema

Error message

vindex %s not found in vschema

What it means

After loading the source keyspace's VSchema, Wrangler looks up the named vindex in sourceVSchema.Vindexes. If the map entry is nil, the vindex does not exist (or is not yet defined) in that keyspace, so externalization cannot proceed.

Source

Thrown at go/vt/wrangler/materializer.go:827

		}
	}
	return "", fmt.Errorf("column %s not found in schema %v", sourceVindexCol, lines)
}

// ExternalizeVindex externalizes a lookup vindex that's finished backfilling or has caught up.
func (wr *Wrangler) ExternalizeVindex(ctx context.Context, qualifiedVindexName string) error {
	splits := strings.Split(qualifiedVindexName, ".")
	if len(splits) != 2 {
		return fmt.Errorf("vindex name should be of the form keyspace.vindex: %s", qualifiedVindexName)
	}
	sourceKeyspace, vindexName := splits[0], splits[1]
	sourceVSchema, err := wr.ts.GetVSchema(ctx, sourceKeyspace)
	if err != nil {
		return err
	}
	sourceVindex := sourceVSchema.Vindexes[vindexName]
	if sourceVindex == nil {
		return fmt.Errorf("vindex %s not found in vschema", qualifiedVindexName)
	}

	targetKeyspace, targetTableName, err := wr.env.Parser().ParseTable(sourceVindex.Params["table"])
	if err != nil || targetKeyspace == "" {
		return fmt.Errorf("vindex table name must be in the form <keyspace>.<table>. Got: %v", sourceVindex.Params["table"])
	}
	workflow := targetTableName + "_vdx"
	targetShards, err := wr.ts.GetServingShards(ctx, targetKeyspace)
	if err != nil {
		return err
	}

	// Create a parallelizer function.
	forAllTargets := func(f func(*topo.ShardInfo) error) error {
		var wg sync.WaitGroup
		allErrors := &concurrency.AllErrorRecorder{}
		for _, targetShard := range targetShards {
			wg.Add(1)

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Run vtctldclient GetVSchema <keyspace> and confirm the vindex appears under vindexes.
2. Correct the keyspace or vindex name to match the vschema definition.
3. If the vindex is missing, add it back to the vschema (ApplyVSchema) before externalizing.

Example fix

// before
wr.ExternalizeVindex(ctx, "customer.corder_vdx") // vindex lives in commerce
// after
wr.ExternalizeVindex(ctx, "commerce.corder_vdx")

vschema := mustGetVSchema(t, ctx, "commerce")
if _, ok := vschema.Vindexes["corder_vdx"]; !ok {
  return fmt.Errorf("vindex corder_vdx not present in commerce vschema")
}

if err := wr.ExternalizeVindex(ctx, "commerce.corder_vdx"); err != nil {
  if strings.Contains(err.Error(), "not found in vschema") {
    // fetch GetVSchema and log available vindexes before retrying
  }
}

When it happens

Trigger: ExternalizeVindex called with keyspace.vindex where vindex is misspelled, was never added to the keyspace vschema, or was already removed/externalized.

Common situations: Backfill workflow was run against a different keyspace than the one named in the ExternalizeVindex call; vindex was deleted from the vschema after backfill; typo in vindex name; pointing at the target keyspace instead of the source keyspace.

Related errors

• one or two tables must be specified
• at least one table must be specified
• vindex is in write-only mode
• vindex has no owner
• no sharded vschema was provided, so you will need to update

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