{"record":{"id":"1a9ebebb1ef6b0ce","repo":"vitessio/vitess","slug":"the-index-of-the-shard-must-be-less-than-the-total","errorCode":null,"errorMessage":"the index of the shard must be less than the total number of shards: %v < %v","messagePattern":"the index of the shard must be less than the total number of shards: (.+?) < (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"go/vt/key/key.go","lineNumber":345,"sourceCode":"// i starts at 0.\n//\n// Example: (1, 2) returns the second out of two shards in total i.e. \"80-\".\n//\n// This function must not be used in the Vitess code base because Vitess also\n// supports shards with different widths. In that case, the output of this\n// function would be wrong.\n//\n// Note: start and end values have trailing zero bytes omitted.\n// For example, \"80-\" has only the first byte (0x80) set.\n// We do this to produce the same KeyRange objects as ParseKeyRangeParts() does.\n// Because it's using the Go hex methods, it's omitting trailing zero bytes as\n// well.\nfunc EvenShardsKeyRange(i, n int) (*topodatapb.KeyRange, error) {\n\tif n <= 0 {\n\t\treturn nil, fmt.Errorf(\"the shard count must be > 0: %v\", n)\n\t}\n\tif i >= n {\n\t\treturn nil, fmt.Errorf(\"the index of the shard must be less than the total number of shards: %v < %v\", i, n)\n\t}\n\tif n&(n-1) != 0 {\n\t\treturn nil, fmt.Errorf(\"the shard count must be a power of two: %v\", n)\n\t}\n\n\t// Determine the number of bytes which are required to represent any\n\t// KeyRange start or end for the given n.\n\t// This is required to trim the returned values to the same length e.g.\n\t// (256, 512) should return 8000-8080 as shard key range.\n\tminBytes := 0\n\tfor nn := Uint64Key(n - 1); nn > 0; nn >>= 8 {\n\t\tminBytes++\n\t}\n\n\twidth := Uint64Key(math.MaxUint64)/Uint64Key(n) + 1\n\tstart := Uint64Key(i) * width\n\tend := start + width\n","sourceCodeStart":327,"sourceCodeEnd":363,"githubUrl":"https://github.com/vitessio/vitess/blob/01a25a7d176f94613b8d59d799f438380a8760e4/go/vt/key/key.go#L327-L363","documentation":"EvenShardsKeyRange(i, n) throws this when the requested shard index i is >= the total shard count n. There is no keyrange for an out-of-range index, so the call fails rather than returning a bogus range.","triggerScenarios":"Calling EvenShardsKeyRange with i >= n, e.g. EvenShardsKeyRange(5, 4). Common in loops that iterate with the wrong bound, or when i comes from one config value and n from another.","commonSituations":"Off-by-one loop conditions (i <= n), user requesting a specific shard of a smaller keyspace, mixing shard indices computed against a different shard count after a reshard.","solutions":["Ensure the caller only requests i in [0, n-1].","Fix loop bounds to iterate `for i := 0; i < n; i++`.","Recompute shard indices against the current shard count after resharding operations."],"exampleFix":"// before\nfor i := 0; i <= shards; i++ { key.EvenShardsKeyRange(i, shards) }\n// after\nfor i := 0; i < shards; i++ { key.EvenShardsKeyRange(i, shards) }","handlingStrategy":"validation","validationCode":"if i < 0 || i >= shards {\n\treturn fmt.Errorf(\"shard index %d out of range [0,%d)\", i, shards)\n}","typeGuard":null,"tryCatchPattern":"kr, err := key.EvenShardsKeyRange(i, n)\nif err != nil {\n\treturn nil, fmt.Errorf(\"range for shard %d: %w\", i, err)\n}","preventionTips":["Loop with i < n, not i <= n","Recompute indices after resharding instead of reusing stale shard indices"],"tags":["go","sharding","input-validation","off-by-one"],"backgroundTag":"invalid-shard-count","analyzedSha":"01a25a7d176f94613b8d59d799f438380a8760e4","analyzedAt":"2026-09-01T17:28:30.605Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}