vitessio/vitess · error

could not parse shard name %q: %+v

Error message

could not parse shard name %q: %+v

What it means

VTOrc validates each cluster-to-watch entry of the form 'keyspace/shard-spec' before using it. After the keyspace/shard part passes IsValidKeyRange, key.ParseShardingSpec must translate the spec (e.g. '-', '-', '-80,80-') into KeyRanges; if that parsing fails this error is returned and VTOrc cannot build its shardsToWatch map, aborting discovery/initialization.

Source

Thrown at go/vt/vtorc/logic/tablet_discovery.go:191

	if len(clustersToWatch) == 0 {
		return nil
	}

	for _, ks := range clustersToWatch {
		if strings.Contains(ks, "/") && !strings.HasSuffix(ks, "/") {
			// Validate keyspace/shard parses.
			k, s, err := topoproto.ParseKeyspaceShard(ks)
			if err != nil {
				log.Error(fmt.Sprintf("Could not parse keyspace/shard %q: %+v", ks, err))
				continue
			}
			if !key.IsValidKeyRange(s) {
				return fmt.Errorf("invalid key range %q while parsing clusters to watch", s)
			}
			// Parse the shard name into key range value.
			keyRanges, err := key.ParseShardingSpec(s)
			if err != nil {
				return fmt.Errorf("could not parse shard name %q: %+v", s, err)
			}
			shardsToWatch[k] = append(shardsToWatch[k], keyRanges...)
		} else {
			// Remove trailing slash if exists.
			ks = strings.TrimSuffix(ks, "/")
			// We store the entire range of key range if nothing is specified.
			shardsToWatch[ks] = []*topodatapb.KeyRange{key.NewCompleteKeyRange()}
		}
	}

	if len(shardsToWatch) == 0 {
		log.Error("No keyspace/shards to watch, watching all keyspaces")
	}
	return nil
}

// shouldWatchTablet checks if the given tablet is part of the watch list.
func shouldWatchTablet(tablet *topodatapb.Tablet) bool {

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Fix the shard spec in the clusters_to_watch config/flag to use valid Vitess shard syntax ('-', '-', '-80', '80-', 'c0-', etc.)
2. Verify with key.ParseShardingSpec semantics: entries must be '-' or N-M / -N / N- numeric ranges
3. If you only want all shards, use the keyspace with an empty shard portion so the whole keyspace is watched
4. Validate the value offline (e.g. in a Go test calling key.IsValidKeyRange and key.ParseShardingSpec) before deploying

Example fix

// before
clustersToWatch = []string{"commerce/primary"}
// after
clustersToWatch = []string{"commerce/-"}

if !key.IsValidKeyRange(spec) || !(func(){ _, err := key.ParseShardingSpec(spec); return err == nil })() {
    return fmt.Errorf("invalid shard spec %q", spec)
}

When it happens

Trigger: Calling initializeShardsToWatch (via OpenTabletDiscovery, RefreshAllKeyspaces/RefreshAllShards, or tests) with a --clusters_to_watch entry whose shard portion is not a valid sharding spec — e.g. 'ks/badshard', 'ks/-abc', 'ks/1-2-3', or an unparseable numeric range.

Common situations: Typo in the clusters-to-watch flag/config; copying a shard name from MySQL rather than Vitess naming conventions; using a keyspace-only entry with a stray suffix; a shard that was split/renamed so the old spec no longer parses.

Related errors

• cell mode should be handled by the gateway, not the balancer
• syslog is not supported on windows
• Log file number is zero, cannot detect previous file
• ReadTopologyInstance(%+v): %+v
• ReadTopologyInstance will not act on empty tablet alias

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