What causes "Invalid segment size: {segmentSize}" in microsoft/FASTER?

Use a power-of-two segment size: 64MB = 1<<26, 1GB = 1<<30, etc.

microsoft/FASTER · error · FasterException

Invalid segment size

Error message

Invalid segment size: {segmentSize}

What it means

Segment sizes must be powers of two because the address space uses bit shifting/masking (segmentSizeBits/segmentSizeMask) for fast segment arithmetic. Initialize checks Utility.IsPowerOfTwo and throws FasterException for any non-power-of-two size other than the special value -1 (which disables segmentation).

Solutions

Use a power-of-two segment size: 64MB = 1<<26, 1GB = 1<<30, etc.
Use the bits-based constructor/factory helpers (segmentSizeBits) to guarantee power-of-two.
Pass segmentSize = -1 if unbounded segment growth is desired.
Round the intended size up to the next power of two (e.g., 100MB -> 128MB).

Example fix

// before
device.Initialize(segmentSize: 100 * 1024 * 1024); // 100 MiB, not a power of two
// after
device.Initialize(segmentSize: 1L << 27); // 128 MiB, power of two

Defensive patterns

Strategy: validation

Validate before calling

static bool IsPowerOfTwo(long x) => x > 0 && (x & (x - 1)) == 0;
if (segmentSize != -1 && !IsPowerOfTwo(segmentSize))
    throw new ArgumentException("segmentSize must be a power of two");

Try / catch

try { device.Initialize(segmentSize, epoch); } catch (FasterException e) when (e.Message.Contains("Invalid segment size")) { /* round to next power of two */ }

Prevention

Use sizes like 64MB (1<<26) or 1GB (1<<30); avoid decimal-round sizes like 100MB.
Prefer bits-based factory parameters (segmentSizeBits) to guarantee power-of-two.
Add a config-time power-of-two assertion.

When it happens

Trigger: Calling Initialize with segmentSize values like 100MB (100 * 1024 * 1024), 10MB, 3GB, or any non-power-of-two byte count.

Common situations: Users converting from sizes in 'round decimal' units (10MB/100MB) instead of binary powers; hardcoding sizes like 500MB; misconfigured bits-to-bytes conversion (e.g., using segmentSizeBits as bytes).

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

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

Appendix: source

Thrown at cs/src/core/Device/StorageDeviceBase.cs:116

        /// <param name="segmentSize"></param>
        /// <param name="epoch"></param>
        /// <param name="omitSegmentIdFromFilename"></param>
        public virtual void Initialize(long segmentSize, LightEpoch epoch = null, bool omitSegmentIdFromFilename = false)
        {
            if (segmentSize != -1)
            { 
                if (Capacity != -1 && Capacity % segmentSize != 0)
                    throw new FasterException("capacity must be a multiple of segment sizes");
                if (omitSegmentIdFromFilename)
                    throw new FasterException("omitSegmentIdInFilename requires a segment size of -1");
            }
            this.segmentSize = segmentSize;
            this.epoch = epoch;
            this.OmitSegmentIdFromFileName = omitSegmentIdFromFilename;
            if (!Utility.IsPowerOfTwo(segmentSize))
            {
                if (segmentSize != -1)
                    throw new FasterException("Invalid segment size: " + segmentSize);
                segmentSizeBits = 64;
                segmentSizeMask = ~0UL;
            }
            else
            {
                segmentSizeBits = Utility.GetLogBase2((ulong)segmentSize);
                segmentSizeMask = (ulong)segmentSize - 1;
            }
        }

        /// <summary>
        /// Create a filename that may or may not include the segmentId
        /// </summary>
        protected internal string GetSegmentFilename(string filename, int segmentId) => GetSegmentFilename(filename, segmentId, OmitSegmentIdFromFileName);

        /// <summary>
        /// Create a filename that may or may not include the segmentId
        /// </summary>

View on GitHub (pinned to 321d872eab)