{"record":{"id":"f118df81fa3a0dce","repo":"microsoft/FASTER","slug":"invalid-segment-size-segmentsize","errorCode":null,"errorMessage":"Invalid segment size: {segmentSize}","messagePattern":"Invalid segment size: (.+?)","errorType":"validation","errorClass":"FasterException","httpStatus":null,"severity":"error","filePath":"cs/src/core/Device/StorageDeviceBase.cs","lineNumber":116,"sourceCode":"        /// <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\n        /// <summary>\n        /// Create a filename that may or may not include the segmentId\n        /// </summary>\n        protected internal string GetSegmentFilename(string filename, int segmentId) => GetSegmentFilename(filename, segmentId, OmitSegmentIdFromFileName);\n\n        /// <summary>\n        /// Create a filename that may or may not include the segmentId\n        /// </summary>","sourceCodeStart":98,"sourceCodeEnd":134,"githubUrl":"https://github.com/microsoft/FASTER/blob/321d872eabda6a0345c8bd76419f89723ed864ae/cs/src/core/Device/StorageDeviceBase.cs#L98-L134","documentation":"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).","triggerScenarios":"Calling Initialize with segmentSize values like 100MB (100 * 1024 * 1024), 10MB, 3GB, or any non-power-of-two byte count.","commonSituations":"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).","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)."],"exampleFix":"// before\ndevice.Initialize(segmentSize: 100 * 1024 * 1024); // 100 MiB, not a power of two\n// after\ndevice.Initialize(segmentSize: 1L << 27); // 128 MiB, power of two","handlingStrategy":"validation","validationCode":"static bool IsPowerOfTwo(long x) => x > 0 && (x & (x - 1)) == 0;\nif (segmentSize != -1 && !IsPowerOfTwo(segmentSize))\n    throw new ArgumentException(\"segmentSize must be a power of two\");","typeGuard":null,"tryCatchPattern":"try { device.Initialize(segmentSize, epoch); } catch (FasterException e) when (e.Message.Contains(\"Invalid segment size\")) { /* round to next power of two */ }","preventionTips":["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."],"tags":["configuration","storage-device","validation","segment-size"],"backgroundTag":"invalid-config-value","analyzedSha":"321d872eabda6a0345c8bd76419f89723ed864ae","analyzedAt":"2026-09-15T22:18:00.693Z","contentChangedAt":"2026-09-15T22:18:00.693Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}