aeron-io/aeron · error · IllegalStateException

Term length more than max length of

Error message

Term length more than max length of {TERM_MAX_LENGTH}: length={termLength}

What it means

Aeron's LogBufferDescriptor.checkTermLength validates that a term buffer length is within the allowed range before a log buffer is created or mapped. This error means the supplied termLength exceeds TERM_MAX_LENGTH (1GB in Aeron), which the transport does not support because term buffers are addressed with a fixed-bit offset scheme. It is thrown as IllegalStateException during channel/subscription configuration.

Solutions

1. Reduce the term-length URI parameter (or Context termBufferLength) to at most 1073741824 (1GB), e.g. aeron.uri()?term-length=1073741824
2. Use a power-of-two value within the supported range (64KB–1GB) and verify with BitUtil.isPowerOfTwo and LogBufferDescriptor.TERM_MAX_LENGTH before use
3. If more buffering is needed, increase IPC/publication termBufferMaxLength at the driver level within limits, or split traffic across multiple channels instead of one giant term buffer

Example fix

// before
final ChannelUri uri = ChannelUri.create(ctx, "aeron:udp?endpoint=localhost:40456|term-length=2147483648");
// after
final ChannelUri uri = ChannelUri.create(ctx, "aeron:udp?endpoint=localhost:40456|term-length=1073741824");

if (termLength > LogBufferDescriptor.TERM_MAX_LENGTH || termLength < LogBufferDescriptor.TERM_MIN_LENGTH)
{
    throw new IllegalArgumentException("term-length must be between " + LogBufferDescriptor.TERM_MIN_LENGTH + " and " + LogBufferDescriptor.TERM_MAX_LENGTH);
}

try { publication = aeron.addPublication(channel, streamId); } catch (final IllegalStateException ex) { if (ex.getMessage().contains("Term length more than max")) { /* fix channel URI config */ } throw ex; }

When it happens

Trigger: Calling Aeron.addPublication/addSubscription (or configuring a channel) with 'term-length' URI parameter, or Aeron.Context setting, greater than 1073741824 (1GB); programmatically passing termLength > TERM_MAX_LENGTH to checkTermLength or log buffer allocation code.

Common situations: Users naively raising term-length hoping to increase throughput (e.g. setting 2GB), copying a config from documentation with a typo like term-length=4294967296, or generating channel URIs programmatically with an unbounded value.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• Term length not a power of 2: length=
• 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/61db1fa6e829a90e. Report an issue: GitHub.

Appendix: source

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

    }

    /**
     * Check that term length is valid and alignment is valid.
     *
     * @param termLength to be checked.
     * @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)

View on GitHub (pinned to 6d60124e15)