What causes "switch command shards not in topo: %v" in vitessio/vitess?

List actual shards with `vtctldclient GetTablets` or topo browse and correct the -shards argument to match exactly.

switch command shards not in topo: %v

Error message

switch command shards not in topo: %v

What it means

CompareShards validates that the shards specified on a switch-traffic/reshard command exactly match the shards recorded in the topology for the keyspace. When the command lists shards that do not exist in the topo (wfExtra), this error is recorded and surfaced as part of a shard-mismatch error. It prevents switching traffic for shards that the topology doesn't know about.

Source

Thrown at go/vt/vtctl/workflow/utils.go:514

	shardSet := sets.New[string]()
	for _, si := range shards {
		shardSet.Insert(si.ShardName())
	}

	topoShards, err := ts.GetShardNames(ctx, keyspace)
	if err != nil {
		return err
	}

	topoShardSet := sets.New[string](topoShards...)
	if !shardSet.Equal(topoShardSet) {
		wfExtra := shardSet.Difference(topoShardSet)
		topoExtra := topoShardSet.Difference(shardSet)

		var rec concurrency.AllErrorRecorder
		if wfExtra.Len() > 0 {
			wfExtraSorted := sets.List(wfExtra)
			rec.RecordError(fmt.Errorf("switch command shards not in topo: %v", wfExtraSorted))
		}

		if topoExtra.Len() > 0 {
			topoExtraSorted := sets.List(topoExtra)
			rec.RecordError(fmt.Errorf("topo shards not in switch command: %v", topoExtraSorted))
		}

		return fmt.Errorf("mismatched shards for keyspace %s: %s", keyspace, strings.Join(rec.ErrorStrings(), "; "))
	}

	return nil
}

// HashStreams produces a stable hash based on the target keyspace and migration
// targets.
func HashStreams(targetKeyspace string, targets map[string]*MigrationTarget) int64 {
	var expanded []string
	for shard, target := range targets {

View on GitHub (pinned to 01a25a7d17)

Solutions

List actual shards with `vtctldclient GetTablets` or topo browse and correct the -shards argument to match exactly.
If shard names changed after a reshard, re-run the switch with the new shard ranges.
Check for formatting differences (leading/trailing hyphens, e.g. `-` vs `0-80`).

Example fix

// before
vtctldclient Reshard --shards=0-c0,d0- SwitchTraffic
// error: switch command shards not in topo: [d0-]
// after
vtctldclient Reshard --shards=0-c0,c0- SwitchTraffic

Defensive patterns

Strategy: validation

Validate before calling

// reconcile your -shards list against the topo before switching
want := sets.New[string](shards...)
have := sets.New[string](topoShardsForKeyspace(ks)...)
if extra := want.Difference(have); extra.Len() > 0 {
    return fmt.Errorf("unknown shards: %v", sets.List(extra))
}

Prevention

Derive shard lists from the topo at runtime instead of hardcoding them.
Update scripts after any Reshard/MergeShards operation.
Normalize shard-name formatting (leading hyphen ranges like `-80`).

When it happens

Trigger: Running SwitchTraffic (via validate) with -shards containing shard names absent from the target keyspace's topo — e.g. shard names from a different keyspace, typo'd shard ranges, or shards removed by a prior merge/reshard.

Common situations: Stale command-line scripts referencing pre-reshard shard names; copying shard lists between keyspaces; typos like `-80` vs `-80-` formatting differences.

Related errors

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