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

Include every topo shard in the -shards list, or verify that a partial switch is actually intended and use the appropriate per-shard workflow commands.

vitessio/vitess · error

topo shards not in switch command: %v

Error message

topo shards not in switch command: %v

What it means

The mirror-image of the previous check: CompareShards found shards present in the topology but not included in the switch command's shard list (topoExtra). A partial shard list would leave some shards un-switched, so validation fails with this recorded error aggregated into the shard-mismatch message.

Source

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

	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 {
		for uid := range target.Sources {
			expanded = append(expanded, fmt.Sprintf("%s:%d", shard, uid))
		}
	}

View on GitHub (pinned to 01a25a7d17)

Solutions

Include every topo shard in the -shards list, or verify that a partial switch is actually intended and use the appropriate per-shard workflow commands.
Enumerate shards from the topo (GetTablets / topo shards for the keyspace) and reconcile against the command.
After a reshard, switch all new shards together in one command.

Example fix

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

Defensive patterns

Strategy: validation

Validate before calling

// ensure the switch covers every topo shard
have := sets.New[string](topoShardsForKeyspace(ks)...)
want := sets.New[string](shards...)
if missing := have.Difference(want); missing.Len() > 0 {
    return fmt.Errorf("missing shards in command: %v", sets.List(missing))
}

Prevention

Always switch all shards of the keyspace together unless intentionally partial.
Regenerate shard lists after resharding operations.
Diff your command's shard list against GetTablets output before running.

When it happens

Trigger: Running SwitchTraffic/validate with a -shards subset that omits one or more shards that exist in the keyspace's topo — e.g. switching only `-80` while `80-` still exists.

Common situations: Partial cutover attempts during Reshard; scripted commands written when the keyspace had fewer shards; forgetting to include newly created shards.

Related errors

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