{"record":{"id":"2043d906281eec35","repo":"aeron-io/aeron","slug":"invalid-term-buffer-length-termbufferlength","errorCode":null,"errorMessage":"invalid term buffer length: ${termBufferLength}","messagePattern":"invalid term buffer length: (.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"aeron-client/src/main/java/io/aeron/logbuffer/LogBufferDescriptor.java","lineNumber":1069,"sourceCode":"    {\n        return switch (termBufferLength)\n        {\n            case 64 * 1024 -> 16;\n            case 128 * 1024 -> 17;\n            case 256 * 1024 -> 18;\n            case 512 * 1024 -> 19;\n            case 1024 * 1024 -> 20;\n            case 2 * 1024 * 1024 -> 21;\n            case 4 * 1024 * 1024 -> 22;\n            case 8 * 1024 * 1024 -> 23;\n            case 16 * 1024 * 1024 -> 24;\n            case 32 * 1024 * 1024 -> 25;\n            case 64 * 1024 * 1024 -> 26;\n            case 128 * 1024 * 1024 -> 27;\n            case 256 * 1024 * 1024 -> 28;\n            case 512 * 1024 * 1024 -> 29;\n            case 1024 * 1024 * 1024 -> 30;\n            default -> throw new IllegalArgumentException(\"invalid term buffer length: \" + termBufferLength);\n        };\n    }\n\n    /**\n     * Compute frame length for a message that is fragmented into chunks of {@code maxPayloadSize}.\n     *\n     * @param length         of the message.\n     * @param maxPayloadSize fragment size without the header.\n     * @return message length after fragmentation.\n     */\n    public static int computeFragmentedFrameLength(final int length, final int maxPayloadSize)\n    {\n        final int numMaxPayloads = length / maxPayloadSize;\n        final int remainingPayload = length % maxPayloadSize;\n        final int lastFrameLength =\n            remainingPayload > 0 ? align(remainingPayload + HEADER_LENGTH, FRAME_ALIGNMENT) : 0;\n\n        return (numMaxPayloads * (maxPayloadSize + HEADER_LENGTH)) + lastFrameLength;","sourceCodeStart":1051,"sourceCodeEnd":1087,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-client/src/main/java/io/aeron/logbuffer/LogBufferDescriptor.java#L1051-L1087","documentation":"This comes from converting a term buffer length into its position-bits exponent (log2). Only lengths that are exact powers of two from 64KB to 1GB map to a shift value; anything else hits the default branch and throws IllegalArgumentException('invalid term buffer length'). It signals an unusable term buffer size for Aeron's offset arithmetic.","triggerScenarios":"Calling termBufferLength-to-shift helpers (e.g. LogBufferDescriptor.termLengthToPositionBits / verifyTermBufferLength style switch) with values like 32MB-1, 100MB, or 2GB; mapping a log file whose recorded term length is corrupt or from an incompatible Aeron version.","commonSituations":"Corrupted or hand-edited log/CnP metadata files, replaying recordings produced with exotic lengths, or programmatic configuration that bypassed checkTermLength.","solutions":["Use only power-of-two term lengths in the 65536..1073741824 range (call LogBufferDescriptor.checkTermLength first to get a clear error)","If reading an existing log buffer, verify its stored term length matches a supported value and recreate/recording-repair the log if corrupted","Ensure the driver and client Aeron versions agree on supported term lengths"],"exampleFix":"// before\nfinal long bits = LogBufferDescriptor.termLengthToPositionBits(100_000_000); // throws\n// after\nfinal int termLength = BitUtil.findNextPositivePowerOfTwo(100_000_000); // 134217728\nLogBufferDescriptor.checkTermLength(termLength);\nfinal long bits = LogBufferDescriptor.termLengthToPositionBits(termLength);","handlingStrategy":"validation","validationCode":"LogBufferDescriptor.checkTermLength(termBufferLength); // throws IllegalStateException early with clearer message","typeGuard":null,"tryCatchPattern":"try { final long bits = LogBufferDescriptor.termLengthToPositionBits(len); } catch (final IllegalArgumentException ex) { if (ex.getMessage().startsWith(\"invalid term buffer length\")) { /* validate/repair source buffer */ } throw ex; }","preventionTips":["Validate any buffer length read from files before converting it","Keep client and driver Aeron versions aligned","Only create log buffers through APIs that call checkTermLength"],"tags":["aeron","term-buffer","validation"],"backgroundTag":"invalid-argument-value","analyzedSha":"6d60124e15e35c11b49ba2e3c2c2858a09a18803","analyzedAt":"2026-09-12T11:17:07.683Z","contentChangedAt":"2026-09-12T11:17:07.683Z","schemaVersion":2},"datasetVersion":"2026-09-19T12:17:13.211Z"}