{"record":{"id":"b2105f85b91b0f7b","repo":"aeron-io/aeron","slug":"term-length-not-a-power-of-2-length-termlength","errorCode":null,"errorMessage":"Term length not a power of 2: length={termLength}","messagePattern":"Term length not a power of 2: length=(.+?)","errorType":"validation","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"aeron-client/src/main/java/io/aeron/logbuffer/LogBufferDescriptor.java","lineNumber":468,"sourceCode":"     * @throws IllegalStateException if the length is not as expected.\n     */\n    public static void checkTermLength(final int termLength)\n    {\n        if (termLength < TERM_MIN_LENGTH)\n        {\n            throw new IllegalStateException(\n                \"Term length less than min length of \" + TERM_MIN_LENGTH + \": length=\" + termLength);\n        }\n\n        if (termLength > TERM_MAX_LENGTH)\n        {\n            throw new IllegalStateException(\n                \"Term length more than max length of \" + TERM_MAX_LENGTH + \": length=\" + termLength);\n        }\n\n        if (!BitUtil.isPowerOfTwo(termLength))\n        {\n            throw new IllegalStateException(\"Term length not a power of 2: length=\" + termLength);\n        }\n    }\n\n    /**\n     * Check that page size is valid and alignment is valid.\n     *\n     * @param pageSize to be checked.\n     * @throws IllegalStateException if the size is not as expected.\n     */\n    public static void checkPageSize(final int pageSize)\n    {\n        if (pageSize < PAGE_MIN_SIZE)\n        {\n            throw new IllegalStateException(\n                \"Page size less than min size of \" + PAGE_MIN_SIZE + \": page size=\" + pageSize);\n        }\n\n        if (pageSize > PAGE_MAX_SIZE)","sourceCodeStart":450,"sourceCodeEnd":486,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-client/src/main/java/io/aeron/logbuffer/LogBufferDescriptor.java#L450-L486","documentation":"LogBufferDescriptor.checkTermLength requires the term buffer length to be a power of 2 because Aeron positions within the term buffer using bit shifts and masks derived from the length. A non-power-of-two length (e.g. 1,000,000) cannot be represented as position bits and breaks the ring-buffer arithmetic, so an IllegalStateException is thrown.","triggerScenarios":"Setting term-length in the channel URI or termBufferLength in Aeron.Context to a value like 1000000, 16777217, or any non-power-of-two while creating a publication/subscription or image.","commonSituations":"Hand-computed sizes ('1MB plus a bit'), sizes read from user config files without validation, or unit confusion (e.g. 1,000,000 bytes instead of 1,048,576).","solutions":["Round the term length up to the nearest power of two (e.g. via BitUtil.findNextPositivePowerOfTwo) before passing it to Aeron","Use a canonical size such as 65536, 262144, 1048576, or 1073741824 in the term-length URI parameter","Validate configuration at startup with BitUtil.isPowerOfTwo(termLength) and fail fast with a clear message"],"exampleFix":"// before\nint termLength = 1_000_000;\ncontext.termBufferLength(termLength);\n// after\nint termLength = BitUtil.findNextPositivePowerOfTwo(1_000_000); // 1048576\ncontext.termBufferLength(termLength);","handlingStrategy":"validation","validationCode":"if (!BitUtil.isPowerOfTwo(termLength)) { termLength = BitUtil.findNextPositivePowerOfTwo(termLength); }","typeGuard":null,"tryCatchPattern":"try { aeron.addPublication(channel, streamId); } catch (final IllegalStateException ex) { if (ex.getMessage().startsWith(\"Term length not a power of 2\")) { /* normalize config and retry */ } throw ex; }","preventionTips":["Round all user-supplied buffer sizes with findNextPositivePowerOfTwo before use","Keep canonical size constants in config schemas rather than free integers","Unit-test channel URI generation with sample configs"],"tags":["aeron","configuration","term-buffer","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"}