{"record":{"id":"02e6f948b2e3646c","repo":"vitessio/vitess","slug":"the-given-number-of-shards-d-is-too-high-for-th","errorCode":null,"errorMessage":"the given number of shards (%d) is too high for the given number of characters to use (%d)","messagePattern":"the given number of shards \\((.+?)\\) is too high for the given number of characters to use \\((.+?)\\)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"go/vt/key/key.go","lineNumber":400,"sourceCode":"\tcase shards <= 0:\n\t\treturn nil, errors.New(\"shards must be greater than zero\")\n\tcase shards == 1:\n\t\treturn []string{\"-\"}, nil\n\tcase shards <= 256:\n\t\tif hexWidth == 0 {\n\t\t\thexWidth = 2\n\t\t}\n\tcase shards <= 65536:\n\t\tif hexWidth == 0 {\n\t\t\thexWidth = 4\n\t\t}\n\tdefault:\n\t\treturn nil, errors.New(\"this function does not support more than 65536 shards in a single keyspace\")\n\t}\n\n\tmaxShards := math.Pow(16, float64(hexWidth))\n\tif shards > int(maxShards) {\n\t\treturn nil, fmt.Errorf(\"the given number of shards (%d) is too high for the given number of characters to use (%d)\", shards, hexWidth)\n\t}\n\n\tformat := fmt.Sprintf(\"%%0%dx\", hexWidth)\n\n\trangeFormatter := func(start, end int) string {\n\t\tvar (\n\t\t\tstartKid string\n\t\t\tendKid   string\n\t\t)\n\n\t\tif start != 0 {\n\t\t\tstartKid = fmt.Sprintf(format, start)\n\t\t}\n\n\t\tif end != int(maxShards) {\n\t\t\tendKid = fmt.Sprintf(format, end)\n\t\t}\n","sourceCodeStart":382,"sourceCodeEnd":418,"githubUrl":"https://github.com/vitessio/vitess/blob/01a25a7d176f94613b8d59d799f438380a8760e4/go/vt/key/key.go#L382-L418","documentation":"GenerateShardRanges generates evenly spaced shard boundaries as hex strings, where each boundary occupies hexWidth characters. Each hex character multiplies the capacity by 16, so with hexWidth characters at most 16^hexWidth shards can be expressed. The library throws when the requested shard count exceeds that capacity.","triggerScenarios":"Calling GenerateShardRanges(shards, numHexCharacters) where shards > 16^numHexCharacters, e.g. GenerateShardRanges(300, 2) (16^2 = 256 < 300).","commonSituations":"Large keyspace setups requesting hundreds/thousands of shards while keeping a small hex width for readability; scripted resharding tools deriving shard count from cluster size without adjusting hex width.","solutions":["Increase numHexCharacters so 16^hexWidth >= shards (e.g. width 3 supports up to 4096 shards).","Reduce the requested shard count.","Handle the returned error and prompt for a larger hex character count in tooling (commandGenerateShardRanges already does this)."],"exampleFix":"// before\nranges, err := key.GenerateShardRanges(300, 2) // too many for 2 hex chars\n// after\nranges, err := key.GenerateShardRanges(300, 3) // 16^3 = 4096 >= 300","handlingStrategy":"validation","validationCode":"if float64(shards) > math.Pow(16, float64(hexWidth)) {\n\treturn fmt.Errorf(\"%d shards need more than %d hex chars\", shards, hexWidth)\n}","typeGuard":null,"tryCatchPattern":"ranges, err := key.GenerateShardRanges(shards, hexWidth)\nif err != nil {\n\treturn nil, fmt.Errorf(\"generate shard ranges: %w\", err)\n}","preventionTips":["Pick hexWidth >= ceil(log16(shards)) for the target shard count","Reuse GenerateShardRanges' own error to prompt users for a larger width, as commandGenerateShardRanges does"],"tags":["go","sharding","capacity-limit","input-validation"],"backgroundTag":"shard-count-exceeds-capacity","analyzedSha":"01a25a7d176f94613b8d59d799f438380a8760e4","analyzedAt":"2026-09-01T17:28:30.605Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}