vitessio/vitess · error

ValidateVSchema(%v, %v, %v, %v) failed: %v

Error message

ValidateVSchema(%v, %v, %v, %v) failed: %v

What it means

ValidateVSchema aggregates all per-shard failures (topo GetShard errors, GetSchema RPC errors, tables missing from vschema) into a ConcurrencyErrorList. If any failures were recorded, this top-level error is returned wrapping the full aggregated message, attributing the failure to the ValidateVSchema call with its keyspace, shards, excludeTables, includeViews arguments.

Source

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

				))
				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)
}

// CopySchemaShardFromShard copies the schema from a source shard to the specified destination shard.
// For both source and destination it picks the primary tablet. See also CopySchemaShard.
func (wr *Wrangler) CopySchemaShardFromShard(ctx context.Context, tables, excludeTables []string, includeViews bool, sourceKeyspace, sourceShard, destKeyspace, destShard string, waitReplicasTimeout time.Duration, skipVerify bool) error {
	sourceShardInfo, err := wr.ts.GetShard(ctx, sourceKeyspace, sourceShard)
	if err != nil {

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Read the aggregated inner message (after 'failed: ') to identify the per-shard root causes.
2. Fix each per-shard issue (shard existence, tablet health, vschema entries) per the inner errors.
3. Re-run ValidateVSchema after remediation to get a clean pass.
4. Ensure the correct shard list was passed (no stale shard names).

Example fix

// before: wrapper hides detail
ValidateVSchema(commerce, ["0","-"]) failed: "/0 has tables that are not in the vschema: [orders]"
// after: fix vschema then re-run
vtctldclient ApplyVSchema --vschema=$(cat vschema.json) commerce
wr.ValidateVSchema(ctx, "commerce", []string{"0"}, nil, nil, true)

// pre-validate each shard and vschema before the aggregate call
for _, shard := range shards {
	if _, err := ts.GetShard(ctx, ks, shard); err != nil { return err }
}
if _, err := ts.GetVSchema(ctx, ks); err != nil { return err }

err := wr.ValidateVSchema(ctx, ks, shards, excludeTables, includeViews, includeViews)
if err != nil {
	var wErr *vterrors.VtError
	if errors.As(err, &wErr) { /* inspect aggregated per-shard causes */ }
	return err
}

When it happens

Trigger: Any invocation of ValidateVSchema (directly or via ValidateSchemaShard / vtctl ValidateVSchema command) where at least one shard goroutine recorded a failure — shard lookup failed, schema fetch failed, or tables were missing from the vschema.

Common situations: Composite failure during a validation audit: mixed causes such as one shard down plus another shard with drifted vschema; users see this wrapper and must read the inner aggregated message for per-shard detail.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• one or two tables must be specified
• at least one table must be specified
• validateWorkflowName.VReplicationExec: <dynamic validation.m
• table %v not found in vschema
• source and target table names must match for copying schema:

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