microsoft/garnet · error · TsavoriteException

{nameof(logSettings.MaxInlineKeySize)} must be between {LogS

Q: What causes "{nameof(logSettings.MaxInlineKeySize)} must be between {LogSettings.MinMaxInlineSize} and {LogSettings.MaxInlineKeySizeLimit}" in microsoft/garnet?

Keep MaxInlineKeySize within [0, 1022]; leave the default 128 unless measured.

Error message

{nameof(logSettings.MaxInlineKeySize)} must be between {LogSettings.MinMaxInlineSize} and {LogSettings.MaxInlineKeySizeLimit}

What it means

Constructor validation: logSettings.MaxInlineKeySize must be in [MinMaxInlineSize, MaxInlineKeySizeLimit] = [0, (1<<RecordDataHeader.kKeyLengthBits)-2] = [0, 1022]. Keys up to this many bytes are stored inline in the in-memory record; larger keys go to overflow. The upper limit is dictated by the 10-bit KeyLength field of RecordDataHeader. Default is 128.

Source

Thrown at libs/storage/Tsavorite/cs/src/core/Allocator/AllocatorBase.cs:581

            if (logSettings.ReadCacheSettings is not null)
            {
                var rcs = logSettings.ReadCacheSettings;
                if (rcs.PageCount == 0 && rcs.MemorySize == 0)
                    throw new TsavoriteException($"{nameof(rcs.PageCount)} or {nameof(rcs.MemorySize)} must be specified");
                if (rcs.PageSizeBits < LogSettings.kMinPageSizeBits || rcs.PageSizeBits > LogSettings.kMaxPageSizeBits)
                    throw new TsavoriteException($"{nameof(rcs.PageSizeBits)} must be between {LogSettings.kMinPageSizeBits} and {LogSettings.kMaxPageSizeBits}");
                if (rcs.PageCount > MemoryUtils.ArrayMaxLength)
                    throw new TsavoriteException($"{nameof(rcs.PageCount)} must be less than or equal to the maximum array length ({MemoryUtils.ArrayMaxLength})");
                if (rcs.MemorySize != 0 && (rcs.MemorySize < 1L << LogSettings.kMinMemorySizeBits || rcs.MemorySize > 1L << LogSettings.kMaxMemorySizeBits))
                    throw new TsavoriteException($"{nameof(rcs.MemorySize)} must be between {1L << LogSettings.kMinMemorySizeBits} and {1L << LogSettings.kMaxMemorySizeBits}");
                if ((rcs.MemorySize != 0) && (rcs.MemorySize < (1L << rcs.PageSizeBits) * 2))
                    throw new TsavoriteException($"{nameof(logSettings.MemorySize)} must be at least twice the page size ({1L << rcs.PageSizeBits})");
                if (rcs.SecondChanceFraction < 0.0 || rcs.SecondChanceFraction > 1.0)
                    throw new TsavoriteException($"{rcs.SecondChanceFraction} must be >= 0.0 and <= 1.0");
            }

            if (logSettings.MaxInlineKeySize < LogSettings.MinMaxInlineSize || logSettings.MaxInlineKeySize > LogSettings.MaxInlineKeySizeLimit)
                throw new TsavoriteException($"{nameof(logSettings.MaxInlineKeySize)} must be between {LogSettings.MinMaxInlineSize} and {LogSettings.MaxInlineKeySizeLimit}");
            if (logSettings.MaxInlineValueSize < LogSettings.MinMaxInlineSize || logSettings.MaxInlineValueSize > LogSettings.MaxInlineValueSizeLimit)
                throw new TsavoriteException($"{nameof(logSettings.MaxInlineValueSize)} must be between {LogSettings.MinMaxInlineSize} and {LogSettings.MaxInlineValueSizeLimit}");

            this.logger = logger;
            if (logSettings.LogDevice == null)
                throw new TsavoriteException("LogSettings.LogDevice needs to be specified (e.g., use Devices.CreateLogDevice, AzureStorageDevice, or NullDevice)");

            EvictCallback = evictCallback;

            FlushCallback = flushCallback;
            PreallocateLog = logSettings.PreallocateLog;
            flushEvent.Initialize();

            IsNullDevice = logSettings.LogDevice is NullDevice;

            if (epoch == null)
            {
                this.epoch = new LightEpoch();

View on GitHub (pinned to 951b0fc683)

Solutions

Keep MaxInlineKeySize within [0, 1022]; leave the default 128 unless measured.
For keys larger than 1022 bytes, rely on the overflow path (do not raise MaxInlineKeySize).
For a pure object store, 0 is allowed (MinMaxInlineSize).

Example fix

// before
logSettings.MaxInlineKeySize = 2048;  // exceeds 1022 (10-bit field)
// after
logSettings.MaxInlineKeySize = 1022;  // field maximum; larger keys overflow

Defensive patterns

Strategy: validation

Validate before calling

const int MaxInlineKey = (1 << 10) - 2; // MaxInlineKeySizeLimit = 1022 (10-bit KeyLength field)
if (logSettings.MaxInlineKeySize < 0 || logSettings.MaxInlineKeySize > MaxInlineKey)
    logSettings.MaxInlineKeySize = Math.Clamp(logSettings.MaxInlineKeySize, 0, MaxInlineKey);

Try / catch

try { new TsavoriteKV<K,V>(logSettings, ...); }
catch (TsavoriteException ex) when (ex.Message.Contains("MaxInlineKeySize"))
{ /* clamp to [0,1022]; let larger keys overflow */ }

Prevention

Do not raise MaxInlineKeySize above 1022; rely on the overflow path for bigger keys.
Keep the default 128 unless measurement shows benefit.
Surface key-size config with explicit clamping in your settings loader.

When it happens

Trigger: Setting MaxInlineKeySize > 1022 (e.g. 2048 hoping for bigger inline keys) or below 0.

Common situations: Trying to inline larger keys for latency reasons and exceeding the 10-bit header field width; negative value from an unset config sentinel.

Related errors

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