vitessio/vitess · error

the given number of shards (%d) is too high for the given nu

Error message

the given number of shards (%d) is too high for the given number of characters to use (%d)

What it means

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.

Source

Thrown at go/vt/key/key.go:400

	case shards <= 0:
		return nil, errors.New("shards must be greater than zero")
	case shards == 1:
		return []string{"-"}, nil
	case shards <= 256:
		if hexWidth == 0 {
			hexWidth = 2
		}
	case shards <= 65536:
		if hexWidth == 0 {
			hexWidth = 4
		}
	default:
		return nil, errors.New("this function does not support more than 65536 shards in a single keyspace")
	}

	maxShards := math.Pow(16, float64(hexWidth))
	if shards > int(maxShards) {
		return nil, fmt.Errorf("the given number of shards (%d) is too high for the given number of characters to use (%d)", shards, hexWidth)
	}

	format := fmt.Sprintf("%%0%dx", hexWidth)

	rangeFormatter := func(start, end int) string {
		var (
			startKid string
			endKid   string
		)

		if start != 0 {
			startKid = fmt.Sprintf(format, start)
		}

		if end != int(maxShards) {
			endKid = fmt.Sprintf(format, end)
		}

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Increase numHexCharacters so 16^hexWidth >= shards (e.g. width 3 supports up to 4096 shards).
2. Reduce the requested shard count.
3. Handle the returned error and prompt for a larger hex character count in tooling (commandGenerateShardRanges already does this).

Example fix

// before
ranges, err := key.GenerateShardRanges(300, 2) // too many for 2 hex chars
// after
ranges, err := key.GenerateShardRanges(300, 3) // 16^3 = 4096 >= 300

if float64(shards) > math.Pow(16, float64(hexWidth)) {
	return fmt.Errorf("%d shards need more than %d hex chars", shards, hexWidth)
}

ranges, err := key.GenerateShardRanges(shards, hexWidth)
if err != nil {
	return nil, fmt.Errorf("generate shard ranges: %w", err)
}

When it happens

Trigger: Calling GenerateShardRanges(shards, numHexCharacters) where shards > 16^numHexCharacters, e.g. GenerateShardRanges(300, 2) (16^2 = 256 < 300).

Common situations: 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.

Related errors

• malformed spec: MinKey/MaxKey cannot be in the middle of the
• malformed spec: shard limits should be in order: %q
• the shard count must be > 0: %v
• the index of the shard must be less than the total number of
• the shard count must be a power of two: %v

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