{"record":{"id":"c9906019c638f6d9","repo":"aeron-io/aeron","slug":"segment-file-length-not-a-power-of-2-segmentfilelength","errorCode":null,"errorMessage":"segment file length not a power of 2: ${segmentFileLength}","messagePattern":"segment file length not a power of 2: (.+?)","errorType":"exception","errorClass":"ArchiveException","httpStatus":null,"severity":"error","filePath":"aeron-archive/src/main/java/io/aeron/archive/Archive.java","lineNumber":1482,"sourceCode":"                            aeron,\n                            tempBuffer,\n                            AeronCounters.ARCHIVE_MAX_CYCLE_TIME_TYPE_ID,\n                            \"archive-replayer max cycle time in ns: \" + threadingMode.name(),\n                            archiveId),\n                        ArchiveCounters.allocate(\n                            aeron,\n                            tempBuffer,\n                            AeronCounters.ARCHIVE_CYCLE_TIME_THRESHOLD_EXCEEDED_TYPE_ID,\n                            \"archive-replayer work cycle time exceeded count: threshold=\" +\n                                SystemUtil.formatDuration(replayerCycleThresholdNs) + \" \" + threadingMode.name(),\n                            archiveId),\n                        replayerCycleThresholdNs);\n                }\n            }\n\n            if (!isPowerOfTwo(segmentFileLength))\n            {\n                throw new ArchiveException(\"segment file length not a power of 2: \" + segmentFileLength);\n            }\n            else if (segmentFileLength < TERM_MIN_LENGTH || segmentFileLength > TERM_MAX_LENGTH)\n            {\n                throw new ArchiveException(\"segment file length not in valid range: \" + segmentFileLength);\n            }\n\n            if (null == authenticatorSupplier)\n            {\n                authenticatorSupplier = Configuration.authenticatorSupplier();\n            }\n\n            if (null == authorisationServiceSupplier)\n            {\n                authorisationServiceSupplier = Configuration.authorisationServiceSupplier();\n            }\n\n            concludeRecordChecksum();\n            concludeReplayChecksum();","sourceCodeStart":1464,"sourceCodeEnd":1500,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-archive/src/main/java/io/aeron/archive/Archive.java#L1464-L1500","documentation":"Archive validates that the configured segment file length is a power of two because recordings are segmented by masking addresses with (segmentFileLength - 1). Archive throws ArchiveException during context configuration if segmentFileLength is not a power of 2.","triggerScenarios":"Setting Archive.Context.segmentFileLength(...) to a non-power-of-2 value such as 100MB (104857600) or 3GB, then launching the archive.","commonSituations":"Administrators sizing segments in decimal units (e.g. 500MB) instead of binary powers; programmatic config derived from user input without validation.","solutions":["Set segmentFileLength to a power of two within TERM_MIN_LENGTH..TERM_MAX_LENGTH (e.g. 1GB = 1 << 30).","Round the desired value up to the next power of two before configuring.","Validate user-supplied sizes with BitUtil.isPowerOfTwo before calling segmentFileLength."],"exampleFix":"// before\nctx.segmentFileLength(500 * 1024 * 1024); // not a power of 2\n// after\nctx.segmentFileLength(1 << 29); // 512MiB, power of 2","handlingStrategy":"validation","validationCode":"if (!BitUtil.isPowerOfTwo(segmentFileLength))\n{\n    throw new IllegalArgumentException(\"segmentFileLength must be a power of 2: \" + segmentFileLength);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Express segment sizes as bit shifts (1 << 30) instead of decimal literals","Validate user-supplied sizes before configuring Archive.Context"],"tags":["aeron","archive","configuration","validation"],"backgroundTag":"invalid-config-value","analyzedSha":"6d60124e15e35c11b49ba2e3c2c2858a09a18803","analyzedAt":"2026-09-12T11:17:07.683Z","contentChangedAt":"2026-09-12T11:17:07.683Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}