microsoft/garnet · error · GarnetException

Sketch size should be power of 2!

Error message

Sketch size should be power of 2!

What it means

Thrown by the Sketch constructor when keyCount is not a positive power of two. The bitmap is allocated as keyCount>>3 bytes and addressed with a bitmask, so the power-of-two requirement is structural, not cosmetic. The default is 1<<20.

Source

Thrown at libs/cluster/Server/Migration/Sketch.cs:25

using Garnet.common;
using Garnet.server;
using Tsavorite.core;

namespace Garnet.cluster
{
    internal class Sketch
    {
        readonly byte[] bitmap;
        readonly int size;
        public readonly ArgSliceVector argSliceVector;

        public List<(PinnedSpanByte, bool)> Keys { private set; get; }
        public SketchStatus Status { private set; get; }

        public Sketch(int keyCount = 1 << 20)
        {
            if (!(keyCount > 0 && (keyCount & (keyCount - 1)) == 0))
                throw new GarnetException($"{nameof(Sketch)} size should be power of 2!");
            size = keyCount;
            bitmap = GC.AllocateArray<byte>(keyCount >> 3, pinned: true);
            Status = SketchStatus.INITIALIZING;
            Keys = [];
            argSliceVector = new();
        }

        #region sketchMethods

        public bool TryHashAndStore(ReadOnlySpan<byte> key)
        {
            if (!argSliceVector.TryAddItem(key))
                return false;

            var slot = (int)HashUtils.MurmurHash2x64A(key) & (size - 1);
            var byteOffset = slot >> 3;
            var bitOffset = slot & 7;
            bitmap[byteOffset] = (byte)(bitmap[byteOffset] | (1UL << bitOffset));

View on GitHub (pinned to 951b0fc683)

Solutions

1. Round the requested size up to the next power of two before constructing the Sketch (e.g. BitOperations.RoundUpToPowerOf2).
2. Clamp the input to a sensible minimum (e.g. 1<<10) before rounding.
3. Validate at the call site and surface a clear error to the operator rather than the raw exception.

Example fix

// before
var sketch = new Sketch(estimatedKeyCount);
// after
using System.Numerics;
var size = (int)BitOperations.RoundUpToPowerOf2((uint)Math.Max(1, estimatedKeyCount));
var sketch = new Sketch(size);

// Normalize to a valid power-of-two size before construction
using System.Numerics;
int size = (int)BitOperations.RoundUpToPowerOf2((uint)Math.Max(1, requestedKeyCount));
if (size <= 0) throw new ArgumentOutOfRangeException(nameof(requestedKeyCount));
var sketch = new Sketch(size);

When it happens

Trigger: Constructing new Sketch(n) where n <= 0 or n is not a power of two (e.g. 1_000_000, 7, 0).

Common situations: Passing a user-supplied or computed key-count estimate directly without rounding up to the next power of two; passing 0 for a no-op migration.

Related errors

• Invalid KeyMigrationStatus: {state}
• MigrateSession Invalid TransferOption {transferOption}
• Invalid SETSLOT Operation
• Failed to validate main store metadata at insertion
• Invalid ClusterConfig payload: too short to contain a versio

AI-assisted analysis of microsoft/garnet@951b0fc683 (2026-08-13). Data as JSON: /api/errors/19269c796009d032. Report an issue: GitHub.