{"record":{"id":"3d240d98b27c3976","repo":"vitessio/vitess","slug":"invalid-key-range-q-while-parsing-clusters-to-wat","errorCode":null,"errorMessage":"invalid key range %q while parsing clusters to watch","messagePattern":"invalid key range %q while parsing clusters to watch","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"go/vt/vtorc/logic/tablet_discovery.go","lineNumber":186,"sourceCode":"\n// initializeShardsToWatch parses the --clusters_to_watch flag-value\n// into a map of keyspace/shards.\nfunc initializeShardsToWatch() error {\n\tshardsToWatch = make(map[string][]*topodatapb.KeyRange)\n\tif len(clustersToWatch) == 0 {\n\t\treturn nil\n\t}\n\n\tfor _, ks := range clustersToWatch {\n\t\tif strings.Contains(ks, \"/\") && !strings.HasSuffix(ks, \"/\") {\n\t\t\t// Validate keyspace/shard parses.\n\t\t\tk, s, err := topoproto.ParseKeyspaceShard(ks)\n\t\t\tif err != nil {\n\t\t\t\tlog.Error(fmt.Sprintf(\"Could not parse keyspace/shard %q: %+v\", ks, err))\n\t\t\t\tcontinue\n\t\t\t}\n\t\t\tif !key.IsValidKeyRange(s) {\n\t\t\t\treturn fmt.Errorf(\"invalid key range %q while parsing clusters to watch\", s)\n\t\t\t}\n\t\t\t// Parse the shard name into key range value.\n\t\t\tkeyRanges, err := key.ParseShardingSpec(s)\n\t\t\tif err != nil {\n\t\t\t\treturn fmt.Errorf(\"could not parse shard name %q: %+v\", s, err)\n\t\t\t}\n\t\t\tshardsToWatch[k] = append(shardsToWatch[k], keyRanges...)\n\t\t} else {\n\t\t\t// Remove trailing slash if exists.\n\t\t\tks = strings.TrimSuffix(ks, \"/\")\n\t\t\t// We store the entire range of key range if nothing is specified.\n\t\t\tshardsToWatch[ks] = []*topodatapb.KeyRange{key.NewCompleteKeyRange()}\n\t\t}\n\t}\n\n\tif len(shardsToWatch) == 0 {\n\t\tlog.Error(\"No keyspace/shards to watch, watching all keyspaces\")\n\t}","sourceCodeStart":168,"sourceCodeEnd":204,"githubUrl":"https://github.com/vitessio/vitess/blob/01a25a7d176f94613b8d59d799f438380a8760e4/go/vt/vtorc/logic/tablet_discovery.go#L168-L204","documentation":"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.","triggerScenarios":"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.","commonSituations":"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).","solutions":["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)","Copy exact shard names from the topo: vtctl GetShards <keyspace>","Remember range must be start<end in keyspace hex ordering; a single shard name without a dash is rejected by IsValidKeyRange","Restart vtorc after correcting the flag"],"exampleFix":"// before\n--clusters_to_watch commerce/abc,commerce/c-\n// after\n--clusters_to_watch commerce/-80,commerce/80-,customer","handlingStrategy":"validation","validationCode":"import \"vitess.io/vitess/go/vt/key\"\n\nfunc validClusterSpec(spec string) error {\n    ks, shard, found := strings.Cut(spec, \"/\")\n    if !found { return nil } // bare keyspace is fine\n    if !key.IsValidKeyRange(shard) {\n        return fmt.Errorf(\"cluster %q: shard %q is not a valid key range\", spec, shard)\n    }\n    return nil\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Copy shard names exactly from vtctldclient GetShards <keyspace>","Use valid range syntax: '-80', '80-', or comma-separated ranges; bare 'ks' watches the whole keyspace","Lint vtorc flags with key.IsValidKeyRange in a pre-start check","Remember reversed or half-open-garbled ranges like '80-40' are invalid"],"tags":["vtorc","configuration","sharding","keyspace"],"backgroundTag":"invalid-shard-keyrange","analyzedSha":"01a25a7d176f94613b8d59d799f438380a8760e4","analyzedAt":"2026-09-01T17:28:30.605Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}