microsoft/FASTER · error · FasterException

Segment ( ) must be at least of page size ( )

Error message

Segment ({SegmentSize}) must be at least of page size ({PageSize})

What it means

FASTER's hybrid log is divided into segments that must each hold at least one full page (SegmentSize >= PageSize). If SegmentSizeBits yields a segment smaller than the page size (1 << PageSizeBits), the allocator cannot be initialized and throws. This preserves the invariant that every segment can contain whole pages.

Solutions

1. Increase LogSettings.SegmentSizeBits so it is >= LogSettings.PageSizeBits.
2. Alternatively decrease PageSizeBits so it is <= SegmentSizeBits.
3. Use the default SegmentSizeBits (e.g. 27 on Linux, 30 on Windows) unless you have a specific reason to change it.

Example fix

// before
var settings = new LogSettings {
  LogDevice = Devices.CreateLogDevice("./faster.log"),
  PageSizeBits = 22, // 4MB
  SegmentSizeBits = 20 // 1MB - smaller than a page!
};

// after
var settings = new LogSettings {
  LogDevice = Devices.CreateLogDevice("./faster.log"),
  PageSizeBits = 22, // 4MB
  SegmentSizeBits = 23 // 8MB >= page size
};

if ((1L << settings.SegmentSizeBits) < (1L << settings.PageSizeBits))
    throw new ArgumentException("SegmentSizeBits must be >= PageSizeBits");

bool SegmentAtLeastPage(LogSettings s) => (1L << s.SegmentSizeBits) >= (1L << s.PageSizeBits);

try { var fht = new FasterKV<K, V>(size, settings); }
catch (FasterException ex) when (ex.Message.Contains("must be at least of page size")) { /* adjust SegmentSizeBits */ }

When it happens

Trigger: Configuring LogSettings.SegmentSizeBits < LogSettings.PageSizeBits, e.g. SegmentSizeBits=16 (64KB) with PageSizeBits=20 (1MB).

Common situations: Users tuning down SegmentSizeBits to limit memory or disk granularity without realizing it must stay >= PageSizeBits; copying example configs and scaling values independently.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Insufficient page size to write delta
• LogSettings.LogDevice needs to be specified (e.g., use…
• Memory size ( ) must be configured to be either 1 (i.e., 0…
• Page size must be at least of device sector size
• Local memory device must have a capacity!

AI-assisted analysis of microsoft/FASTER@321d872eab (2026-09-15). Data as JSON: /api/errors/081328e1906a709e. Report an issue: GitHub.

Appendix: source

Thrown at cs/src/core/Allocator/AllocatorBase.cs:1011

            PageSizeMask = PageSize - 1;

            // Total HLOG size
            LogTotalSizeBits = settings.MemorySizeBits;
            LogTotalSizeBytes = 1L << LogTotalSizeBits;
            BufferSize = (int)(LogTotalSizeBytes / (1L << LogPageSizeBits));
            BufferSizeMask = BufferSize - 1;

            LogMutableFraction = settings.MutableFraction;

            EmptyPageCount = 0;

            // Segment size
            LogSegmentSizeBits = settings.SegmentSizeBits;
            SegmentSize = 1L << LogSegmentSizeBits;
            SegmentBufferSize = 1 + (LogTotalSizeBytes / SegmentSize < 1 ? 1 : (int)(LogTotalSizeBytes / SegmentSize));

            if (SegmentSize < PageSize)
                throw new FasterException($"Segment ({SegmentSize}) must be at least of page size ({PageSize})");

            if ((LogTotalSizeBits != 0) && (LogTotalSizeBytes < PageSize))
                throw new FasterException($"Memory size ({LogTotalSizeBytes}) must be configured to be either 1 (i.e., 0 bits) or at least page size ({PageSize})");

            PageStatusIndicator = new FullPageStatus[BufferSize];

            if (!IsNullDevice)
            {
                PendingFlush = new PendingFlushList[BufferSize];
                for (int i = 0; i < BufferSize; i++)
                    PendingFlush[i] = new PendingFlushList();
            }
            device = settings.LogDevice;
            sectorSize = (int)device.SectorSize;

            if (PageSize < sectorSize)
                throw new FasterException($"Page size must be at least of device sector size ({sectorSize} bytes). Set PageSizeBits accordingly.");

View on GitHub (pinned to 321d872eab)