vitessio/vitess · error

invalid key range %q while parsing clusters to watch

Error message

invalid key range %q while parsing clusters to watch

What it means

vtorc's --clusters_to_watch accepts keyspace/shard entries like 'ks1/-80' or 'ks1'. initializeShardsToWatch parses each entry and validates the shard part is a valid key range via key.IsValidKeyRange. An entry whose shard portion is not a valid range aborts startup with this error.

Source

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

// initializeShardsToWatch parses the --clusters_to_watch flag-value
// into a map of keyspace/shards.
func initializeShardsToWatch() error {
	shardsToWatch = make(map[string][]*topodatapb.KeyRange)
	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")
	}

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Fix the shard range syntax in --clusters_to_watch: use valid ranges like '-80', '80-', or '-40,40-' (or omit the shard to watch the whole keyspace)
2. Copy exact shard names from the topo: vtctl GetShards <keyspace>
3. Remember range must be start<end in keyspace hex ordering; a single shard name without a dash is rejected by IsValidKeyRange
4. Restart vtorc after correcting the flag

Example fix

// before
--clusters_to_watch commerce/abc,commerce/c-
// after
--clusters_to_watch commerce/-80,commerce/80-,customer

import "vitess.io/vitess/go/vt/key"

func validClusterSpec(spec string) error {
    ks, shard, found := strings.Cut(spec, "/")
    if !found { return nil } // bare keyspace is fine
    if !key.IsValidKeyRange(shard) {
        return fmt.Errorf("cluster %q: shard %q is not a valid key range", spec, shard)
    }
    return nil
}

When it happens

Trigger: OpenTabletDiscovery -> initializeShardsToWatch when an entry in --clusters_to_watch has a shard name that fails IsValidKeyRange, e.g. 'ks1/abc', 'ks1/80-40' (reversed bounds), or a malformed hex range.

Common situations: Hand-typing shard ranges instead of copying from the topo ('ks/-8-' typos), using reshard intermediate names incorrectly, or forgetting that a bare keyspace must not include a slash ('ks/' is invalid).

Related errors

• keyspace not found
• error parsing shard name %v: %v
• malformed spec: doesn't define a range: %q
• malformed spec: MinKey/MaxKey cannot be in the middle of the
• malformed spec: shard limits should be in order: %q

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