What causes "GetSchema(%s, nil, %v, %v) (%v/%v) failed: %v" in vitessio/vitess?

Check tablet health: vtctl GetAllTablets and verify the primary tablet is serving.

GetSchema(%s, nil, %v, %v) (%v/%v) failed: %v

Error message

GetSchema(%s, nil, %v, %v) (%v/%v) failed: %v

What it means

Inside ValidateVSchema, after fetching the shard record, the wrangler calls schematools.GetSchema on the shard's primary tablet to retrieve its table definitions. This error is recorded when that RPC fails — the primary tablet was unreachable, not serving, or failed to return its schema. The failure is aggregated in shardFailures and surfaced by ValidateVSchema.

Source

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

	}

	shardFailures := concurrency.AllErrorRecorder{}
	var wg sync.WaitGroup
	wg.Add(len(shards))

	for _, shard := range shards {
		go func(shard string) {
			defer wg.Done()
			notFoundTables := []string{}
			si, err := wr.ts.GetShard(ctx, keyspace, shard)
			if err != nil {
				shardFailures.RecordError(fmt.Errorf("GetShard(%v, %v) failed: %v", keyspace, shard, err))
				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()

View on GitHub (pinned to 01a25a7d17)

Solutions

Check tablet health: vtctl GetAllTablets <keyspace> and verify the primary tablet is serving.
Restart or repair the failing vttablet process.
Confirm network connectivity between vtctld and the tablet's gRPC port.
Re-run ValidateVSchema once the primary is healthy; check the wrapped inner error for the specific RPC cause.

Example fix

// before (primary down)
wr.ValidateVSchema(ctx, "commerce", []string{"0"}, nil, nil, true)
// after
// start/restart vttablet on the primary, verify with vtctl GetTablet <alias>, then retry
wr.ValidateVSchema(ctx, "commerce", []string{"0"}, nil, nil, true)

Defensive patterns

Strategy: try-catch

Validate before calling

for _, shard := range shards {
	si, err := ts.GetShard(ctx, ks, shard)
	if err == nil && si.PrimaryAlias != nil {
		_, err = tmc.GetSchema(ctx, si.PrimaryAlias, &tabletmanagerdatapb.GetSchemaRequest{})
	}
	if err != nil { return fmt.Errorf("shard %s/%s unhealthy: %w", ks, shard, err) }
}

Try / catch

if err := wr.ValidateVSchema(ctx, ks, shards, nil, nil, true); err != nil {
	log.Error(err, "per-shard GetSchema failure; check tablet health for each shard primary")
}

Prevention

Run vtctl HealthCheck / tablet health monitoring before schema operations
Avoid running validation during reparents or tablet restarts
Verify primary aliases are set on all shards before validating

When it happens

Trigger: Calling ValidateVSchema when a shard's primary tablet is down, the tabletmanager RPC GetSchema times out or errors, or si.PrimaryAlias points to a non-existent/failed tablet.

Common situations: Primary tablet crashed or was restarted during validation; vttablet process not running; firewall/network partition between vtctld and the tablet; tablet in a non-serving state (e.g. during reparent).

Related errors

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