microsoft/FASTER · error · FasterException

omitSegmentIdInFilename requires a segment size of -1

Error message

omitSegmentIdInFilename requires a segment size of -1

What it means

The omitSegmentIdFromFilename option means a single monolithic file with no segment-id suffix; that only makes sense when there are no segment boundaries, i.e., segmentSize == -1. Initialize rejects any combination where a real segment size is supplied together with this flag.

Solutions

Set segmentSize to -1 when passing omitSegmentIdFromFilename: true.
If you need segmented logs, pass omitSegmentIdFromFilename: false (default).
Remove the omitSegmentIdFromFilename flag if finite segment sizes are required.

Example fix

// before
device.Initialize(segmentSize: 1L << 30, epoch: epoch, omitSegmentIdFromFilename: true);
// after
device.Initialize(segmentSize: -1, epoch: epoch, omitSegmentIdFromFilename: true);

Defensive patterns

Strategy: validation

Validate before calling

if (omitSegmentIdFromFilename && segmentSize != -1)
    throw new ArgumentException("omitSegmentIdFromFilename requires segmentSize == -1");

Try / catch

try { device.Initialize(segmentSize, epoch, omitSegmentId); } catch (FasterException e) when (e.Message.Contains("omitSegmentIdInFilename")) { /* fix config */ }

Prevention

Remember the pairing rule: omitSegmentIdFromFilename only with segmentSize = -1.
Encode the pairing constraint in your configuration validator.
Document that -1 means 'no segmentation', not 'unlimited segments'.

When it happens

Trigger: Calling Initialize(segmentSize, epoch, omitSegmentIdFromFilename: true) with segmentSize set to any value other than -1.

Common situations: Trying to use a single pre-allocated file while still setting a segment size; migrating configs where omitSegmentIdFromFilename was added without adjusting segmentSize; misunderstanding that -1 means 'unlimited segments' rather than 'no segments'.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

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

Appendix: source

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

            segmentSizeMask = ~0UL;

            Capacity = capacity;
        }

        /// <summary>
        /// Initialize device
        /// </summary>
        /// <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;
            }
        }

View on GitHub (pinned to 321d872eab)