aeron-io/aeron · error · IllegalArgumentException

invalid term buffer length

Error message

invalid term buffer length: ${termBufferLength}

What it means

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.

Solutions

1. Use only power-of-two term lengths in the 65536..1073741824 range (call LogBufferDescriptor.checkTermLength first to get a clear error)
2. If reading an existing log buffer, verify its stored term length matches a supported value and recreate/recording-repair the log if corrupted
3. Ensure the driver and client Aeron versions agree on supported term lengths

Example fix

// before
final long bits = LogBufferDescriptor.termLengthToPositionBits(100_000_000); // throws
// after
final int termLength = BitUtil.findNextPositivePowerOfTwo(100_000_000); // 134217728
LogBufferDescriptor.checkTermLength(termLength);
final long bits = LogBufferDescriptor.termLengthToPositionBits(termLength);

LogBufferDescriptor.checkTermLength(termBufferLength); // throws IllegalStateException early with clearer message

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; }

When it happens

Trigger: 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.

Common situations: Corrupted or hand-edited log/CnP metadata files, replaying recordings produced with exotic lengths, or programmatic configuration that bypassed checkTermLength.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Term length more than max length of
• Term length not a power of 2: length=
• Aeron spies are invalid as send destinations: channel=
• AeronArchive.Context.messageRetryAttempts must be > 0, got:
• applicationSpecificFeedback length must be equal to

AI-assisted analysis of aeron-io/aeron@6d60124e15 (2026-09-12). Data as JSON: /api/errors/2043d906281eec35. Report an issue: GitHub.

Appendix: source

Thrown at aeron-client/src/main/java/io/aeron/logbuffer/LogBufferDescriptor.java:1069

    {
        return switch (termBufferLength)
        {
            case 64 * 1024 -> 16;
            case 128 * 1024 -> 17;
            case 256 * 1024 -> 18;
            case 512 * 1024 -> 19;
            case 1024 * 1024 -> 20;
            case 2 * 1024 * 1024 -> 21;
            case 4 * 1024 * 1024 -> 22;
            case 8 * 1024 * 1024 -> 23;
            case 16 * 1024 * 1024 -> 24;
            case 32 * 1024 * 1024 -> 25;
            case 64 * 1024 * 1024 -> 26;
            case 128 * 1024 * 1024 -> 27;
            case 256 * 1024 * 1024 -> 28;
            case 512 * 1024 * 1024 -> 29;
            case 1024 * 1024 * 1024 -> 30;
            default -> throw new IllegalArgumentException("invalid term buffer length: " + termBufferLength);
        };
    }

    /**
     * Compute frame length for a message that is fragmented into chunks of {@code maxPayloadSize}.
     *
     * @param length         of the message.
     * @param maxPayloadSize fragment size without the header.
     * @return message length after fragmentation.
     */
    public static int computeFragmentedFrameLength(final int length, final int maxPayloadSize)
    {
        final int numMaxPayloads = length / maxPayloadSize;
        final int remainingPayload = length % maxPayloadSize;
        final int lastFrameLength =
            remainingPayload > 0 ? align(remainingPayload + HEADER_LENGTH, FRAME_ALIGNMENT) : 0;

        return (numMaxPayloads * (maxPayloadSize + HEADER_LENGTH)) + lastFrameLength;

View on GitHub (pinned to 6d60124e15)