aeron-io/aeron · error · IllegalStateException

Term length not a power of 2: length=

Error message

Term length not a power of 2: length={termLength}

What it means

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.

Solutions

1. Round the term length up to the nearest power of two (e.g. via BitUtil.findNextPositivePowerOfTwo) before passing it to Aeron
2. Use a canonical size such as 65536, 262144, 1048576, or 1073741824 in the term-length URI parameter
3. Validate configuration at startup with BitUtil.isPowerOfTwo(termLength) and fail fast with a clear message

Example fix

// before
int termLength = 1_000_000;
context.termBufferLength(termLength);
// after
int termLength = BitUtil.findNextPositivePowerOfTwo(1_000_000); // 1048576
context.termBufferLength(termLength);

if (!BitUtil.isPowerOfTwo(termLength)) { termLength = BitUtil.findNextPositivePowerOfTwo(termLength); }

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

When it happens

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

Common situations: 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).

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Term length more than max length of
• segment file length not a power of 2
• segment file length not in valid range
• AeronArchive.Context.messageRetryAttempts must be > 0, got:
• difference greater than 2^31 - 1: termId=

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

Appendix: source

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

     * @throws IllegalStateException if the length is not as expected.
     */
    public static void checkTermLength(final int termLength)
    {
        if (termLength < TERM_MIN_LENGTH)
        {
            throw new IllegalStateException(
                "Term length less than min length of " + TERM_MIN_LENGTH + ": length=" + termLength);
        }

        if (termLength > TERM_MAX_LENGTH)
        {
            throw new IllegalStateException(
                "Term length more than max length of " + TERM_MAX_LENGTH + ": length=" + termLength);
        }

        if (!BitUtil.isPowerOfTwo(termLength))
        {
            throw new IllegalStateException("Term length not a power of 2: length=" + termLength);
        }
    }

    /**
     * Check that page size is valid and alignment is valid.
     *
     * @param pageSize to be checked.
     * @throws IllegalStateException if the size is not as expected.
     */
    public static void checkPageSize(final int pageSize)
    {
        if (pageSize < PAGE_MIN_SIZE)
        {
            throw new IllegalStateException(
                "Page size less than min size of " + PAGE_MIN_SIZE + ": page size=" + pageSize);
        }

        if (pageSize > PAGE_MAX_SIZE)

View on GitHub (pinned to 6d60124e15)