microsoft/garnet · error · TsavoriteException

{nameof(logSettings.SegmentSizeBits)} must be between {LogSe

Error message

{nameof(logSettings.SegmentSizeBits)} must be between {LogSettings.kMinMainLogSegmentSizeBits} and {LogSettings.kMaxSegmentSizeBits}

What it means

Constructor validation: logSettings.SegmentSizeBits must be in [LogSettings.kMinMainLogSegmentSizeBits, LogSettings.kMaxSegmentSizeBits] = [12, 62]. Segments are the on-disk grouping of pages and the unit of the DiskWriteBuffer; the bit width feeds segment-offset math. Default is 30 (1GiB).

Source

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

            _wrapper = wrapperCreator(this);

            // Pre-bind the instance-method delegate once so the pending-IO hot path does
            // not allocate a fresh DeviceIOCompletionCallback per AsyncGetFromDisk call.
            asyncGetFromDiskCallbackDelegate = AsyncGetFromDiskCallback;

            this.transientObjectIdMap = transientObjectIdMap;

            // Validation
            if (logSettings.PageCount == 0 && logSettings.MemorySize == 0)
                throw new TsavoriteException($"{nameof(logSettings.PageCount)} or {nameof(logSettings.MemorySize)} must be specified");
            if (logSettings.PageSizeBits < LogSettings.kMinPageSizeBits || logSettings.PageSizeBits > LogSettings.kMaxPageSizeBits)
                throw new TsavoriteException($"{nameof(logSettings.PageSizeBits)} must be between {LogSettings.kMinPageSizeBits} and {LogSettings.kMaxPageSizeBits}");
            if (logSettings.PageSizeBits < PageHeader.SizeBits)
                throw new TsavoriteException($"{nameof(logSettings.PageSizeBits)} must be >= PageHeader.SizeBits {PageHeader.SizeBits}");
            if (logSettings.PageCount > MemoryUtils.ArrayMaxLength)
                throw new TsavoriteException($"{nameof(logSettings.PageCount)} must be less than or equal to the maximum array length ({MemoryUtils.ArrayMaxLength})");
            if (logSettings.SegmentSizeBits < LogSettings.kMinMainLogSegmentSizeBits || logSettings.SegmentSizeBits > LogSettings.kMaxSegmentSizeBits)
                throw new TsavoriteException($"{nameof(logSettings.SegmentSizeBits)} must be between {LogSettings.kMinMainLogSegmentSizeBits} and {LogSettings.kMaxSegmentSizeBits}");
            if (logSettings.MemorySize != 0 && (logSettings.MemorySize < 1L << LogSettings.kMinMemorySizeBits || logSettings.MemorySize > 1L << LogSettings.kMaxMemorySizeBits))
                throw new TsavoriteException($"{nameof(logSettings.MemorySize)} must be between {1L << LogSettings.kMinMemorySizeBits} and {1L << LogSettings.kMaxMemorySizeBits}, or may be 0 for ReadOnly TsavoriteLog");
            if ((logSettings.MemorySize != 0) && (logSettings.MemorySize < (1L << logSettings.PageSizeBits) * LogSettings.kMinPageCount))
                throw new TsavoriteException($"{nameof(logSettings.MemorySize)} must be at least {LogSettings.kMinPageCount}x the page size ({1L << logSettings.PageSizeBits})");
            if (logSettings.MutableFraction < 0.0 || logSettings.MutableFraction > 1.0)
                throw new TsavoriteException($"{nameof(logSettings.MutableFraction)} must be >= 0.0 and <= 1.0");
            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))

View on GitHub (pinned to 951b0fc683)

Solutions

Set SegmentSizeBits within [12, 62]; default 30 (1GiB) is a safe choice.
Ensure SegmentSizeBits >= PageSizeBits to also avoid error 239 downstream.
Remember it is a bit exponent (30 => 1GiB segment).

Example fix

// before
logSettings.SegmentSizeBits = 64;  // above 62-bit ceiling
// after
logSettings.SegmentSizeBits = 30;   // 1GiB, the default

Defensive patterns

Strategy: validation

Validate before calling

const int MinSegBits = 12, MaxSegBits = 62; // LogSettings constants
if (logSettings.SegmentSizeBits < MinSegBits || logSettings.SegmentSizeBits > MaxSegBits)
    throw new ArgumentOutOfRangeException(nameof(logSettings.SegmentSizeBits),
        $"SegmentSizeBits must be in [{MinSegBits},{MaxSegBits}]");
// also keep segment >= page to avoid error 239:
if (logSettings.SegmentSizeBits < logSettings.PageSizeBits)
    logSettings.SegmentSizeBits = logSettings.PageSizeBits;

Try / catch

try { new TsavoriteKV<K,V>(logSettings, ...); }
catch (TsavoriteException ex) when (ex.Message.Contains("SegmentSizeBits") && ex.Message.Contains("between"))
{ /* set SegmentSizeBits to a value in [12,62] and >= PageSizeBits */ }

Prevention

Keep the default SegmentSizeBits=30 unless you have measured reason to change it.
Always keep SegmentSizeBits >= PageSizeBits.
Treat the value as a bit exponent (30 => 1GiB).

When it happens

Trigger: Setting SegmentSizeBits below 12 or above 62 when constructing the store, e.g. `SegmentSizeBits = 10` or `= 64`.

Common situations: Tuning segment size for very large disks and overshooting 62 bits; confusing bits/bytes; copying guidance from a system with different limits.

Related errors

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