aeron-io/aeron · error · util::IllegalStateException

EINVAL

EINVAL

Error message

term length less than min size of {TERM_MIN_LENGTH}, length={termLength}

What it means

LogBufferDescriptor::checkTermLength rejects term lengths below TERM_MIN_LENGTH (64KB) with IllegalStateException (EINVAL), because Aeron term buffers must be at least the minimum size to function correctly.

Solutions

1. Use a term length of at least 64KB (65536).
2. When building a channel URI, set termLength to a legal value: 65536, 131072, ... up to 1GB, power of two.
3. Clamp/normalize user-supplied term lengths before constructing the channel.

Example fix

// before
builder.termLength(16 * 1024);
// after
builder.termLength(64 * 1024);

if (termLength < LogBufferDescriptor::TERM_MIN_LENGTH) termLength = LogBufferDescriptor::TERM_MIN_LENGTH; // then build channel

try { builder.termLength(termLength); } catch (const aeron::util::IllegalStateException& e) { builder.termLength(LogBufferDescriptor::TERM_MIN_LENGTH); }

When it happens

Trigger: Calling checkTermLength (directly or via ChannelUriStringBuilder when validating a termLength parameter) with a value < 64KB, e.g. setting 'termLength' on a ChannelUriStringBuilder to 4096.

Common situations: Setting an URI term-length option too small for low-latency testing (e.g. 16KB or 4KB); copying a term length from another messaging system with smaller defaults; typos like 64_000 instead of 65536 with small suffixes.

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 less than min length of
• MTU greater than max message length for term length: mtu=
• term-length= does not match session-id tag value: channel=
• Aeron client instance must set…
• Aeron client must use a RethrowingErrorHandler

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

Appendix: source

Thrown at aeron-client/src/main/cpp_wrapper/concurrent/logbuffer/LogBufferDescriptor.h:116

 *  +---------------------------------------------------------------+
 *  |                         Term Length                           |
 *  +---------------------------------------------------------------+
 *  |                          Page Size                            |
 *  +---------------------------------------------------------------+
 *  |                      Cache Line Padding                      ...
 * ...                                                              |
 *  +---------------------------------------------------------------+
 *  |                    Default Frame Header                      ...
 * ...                                                              |
 *  +---------------------------------------------------------------+
 * </pre>
 */

inline void checkTermLength(std::int32_t termLength)
{
    if (termLength < TERM_MIN_LENGTH)
    {
        throw util::IllegalStateException(
            "term length less than min size of " + std::to_string(TERM_MIN_LENGTH) +
            ", length=" + std::to_string(termLength), SOURCEINFO, EINVAL);
    }

    if (termLength > TERM_MAX_LENGTH)
    {
        throw util::IllegalStateException(
            "term length greater than max size of " + std::to_string(TERM_MAX_LENGTH) +
            ", length=" + std::to_string(termLength), SOURCEINFO, EINVAL);
    }

    if (!util::BitUtil::isPowerOfTwo(termLength))
    {
        throw util::IllegalStateException(
            "term length not a power of 2, length=" + std::to_string(termLength), SOURCEINFO, EINVAL);
    }
}

View on GitHub (pinned to 6d60124e15)