{"record":{"id":"f39224c443f74074","repo":"microsoft/FASTER","slug":"capacity-must-be-a-multiple-of-segment-sizes","errorCode":null,"errorMessage":"capacity must be a multiple of segment sizes","messagePattern":"capacity must be a multiple of segment sizes","errorType":"validation","errorClass":"FasterException","httpStatus":null,"severity":"error","filePath":"cs/src/core/Device/StorageDeviceBase.cs","lineNumber":106,"sourceCode":"            segmentSize = -1;\n            segmentSizeBits = 64;\n            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            }","sourceCodeStart":88,"sourceCodeEnd":124,"githubUrl":"https://github.com/microsoft/FASTER/blob/321d872eabda6a0345c8bd76419f89723ed864ae/cs/src/core/Device/StorageDeviceBase.cs#L88-L124","documentation":"StorageDeviceBase.Initialize validates that when a finite segment size is used, the device's total Capacity must be an exact multiple of that segment size, since the address space is divided into fixed-size segments. A mismatch means the last segment would not fit, so construction is refused.","triggerScenarios":"Calling Initialize(segmentSize, ...) (directly or via device setup where Capacity was set) with segmentSize != -1 and Capacity % segmentSize != 0 — e.g., Capacity=1GB with segmentSize=3GB, or a device created with capacityLimit that isn't divisible by the chosen segment size.","commonSituations":"Manually constructing LocalStorageDevice/ManagedLocalStorageDevice with a capacityLimit and custom segment size; switching logMemorySizeBits/segmentSizeBits combinations so bits no longer divide evenly; copy-pasted configuration where capacity was changed but segment size was not.","solutions":["Set capacityLimit to a multiple of segmentSize (or 0/-1 for unlimited).","Use power-of-two sizes and derive them from bits (e.g., capacity 2^30 with segmentSize 2^28).","Pass segmentSize = -1 to disable the capacity-multiple requirement (unlimited capacity).","Let device factory helpers (e.g., Devices.CreateLogDevice) compute consistent bits instead of setting raw values."],"exampleFix":"// before\nvar device = new LocalStorageDevice(path, capacity: 1L << 30); // 1 GiB\n...\ndevice.Initialize(segmentSize: 3L << 30); // 3 GiB segment: 1 GiB % 3 GiB != 0\n// after\ndevice.Initialize(segmentSize: 1L << 28); // 256 MiB segments: 1 GiB is an exact multiple","handlingStrategy":"validation","validationCode":"if (segmentSize != -1 && capacity != -1 && capacity % segmentSize != 0)\n    throw new ArgumentException(\"capacity must be a multiple of segmentSize\");","typeGuard":null,"tryCatchPattern":"try { device.Initialize(segmentSize, epoch); } catch (FasterException e) when (e.Message.Contains(\"multiple of segment\")) { /* fix capacity config */ }","preventionTips":["Express capacity and segment sizes as powers of two (1<<n).","Let factory helpers derive bits instead of hand-setting raw byte counts.","Validate the capacity/segmentSize pair in config loading tests."],"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-16T09:17:16.951Z"}