{"record":{"id":"c3c283151aa1f375","repo":"microsoft/FASTER","slug":"omitsegmentidinfilename-requires-a-segment-size-of-1","errorCode":null,"errorMessage":"omitSegmentIdInFilename requires a segment size of -1","messagePattern":"omitSegmentIdInFilename requires a segment size of -1","errorType":"validation","errorClass":"FasterException","httpStatus":null,"severity":"error","filePath":"cs/src/core/Device/StorageDeviceBase.cs","lineNumber":108,"sourceCode":"            segmentSizeMask = ~0UL;\n\n            Capacity = capacity;\n        }\n\n        /// <summary>\n        /// Initialize device\n        /// </summary>\n        /// <param name=\"segmentSize\"></param>\n        /// <param name=\"epoch\"></param>\n        /// <param name=\"omitSegmentIdFromFilename\"></param>\n        public virtual void Initialize(long segmentSize, LightEpoch epoch = null, bool omitSegmentIdFromFilename = false)\n        {\n            if (segmentSize != -1)\n            { \n                if (Capacity != -1 && Capacity % segmentSize != 0)\n                    throw new FasterException(\"capacity must be a multiple of segment sizes\");\n                if (omitSegmentIdFromFilename)\n                    throw new FasterException(\"omitSegmentIdInFilename requires a segment size of -1\");\n            }\n            this.segmentSize = segmentSize;\n            this.epoch = epoch;\n            this.OmitSegmentIdFromFileName = omitSegmentIdFromFilename;\n            if (!Utility.IsPowerOfTwo(segmentSize))\n            {\n                if (segmentSize != -1)\n                    throw new FasterException(\"Invalid segment size: \" + segmentSize);\n                segmentSizeBits = 64;\n                segmentSizeMask = ~0UL;\n            }\n            else\n            {\n                segmentSizeBits = Utility.GetLogBase2((ulong)segmentSize);\n                segmentSizeMask = (ulong)segmentSize - 1;\n            }\n        }\n","sourceCodeStart":90,"sourceCodeEnd":126,"githubUrl":"https://github.com/microsoft/FASTER/blob/321d872eabda6a0345c8bd76419f89723ed864ae/cs/src/core/Device/StorageDeviceBase.cs#L90-L126","documentation":"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.","triggerScenarios":"Calling Initialize(segmentSize, epoch, omitSegmentIdFromFilename: true) with segmentSize set to any value other than -1.","commonSituations":"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'.","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."],"exampleFix":"// before\ndevice.Initialize(segmentSize: 1L << 30, epoch: epoch, omitSegmentIdFromFilename: true);\n// after\ndevice.Initialize(segmentSize: -1, epoch: epoch, omitSegmentIdFromFilename: true);","handlingStrategy":"validation","validationCode":"if (omitSegmentIdFromFilename && segmentSize != -1)\n    throw new ArgumentException(\"omitSegmentIdFromFilename requires segmentSize == -1\");","typeGuard":null,"tryCatchPattern":"try { device.Initialize(segmentSize, epoch, omitSegmentId); } catch (FasterException e) when (e.Message.Contains(\"omitSegmentIdInFilename\")) { /* fix config */ }","preventionTips":["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'."],"tags":["configuration","storage-device","validation","conflicting-options"],"backgroundTag":"conflicting-config-options","analyzedSha":"321d872eabda6a0345c8bd76419f89723ed864ae","analyzedAt":"2026-09-15T22:18:00.693Z","contentChangedAt":"2026-09-15T22:18:00.693Z","schemaVersion":2},"datasetVersion":"2026-09-16T09:17:16.951Z"}