aeron-io/aeron · error · IllegalStateException

Term length less than min length of

Error message

Term length less than min length of {TERM_MIN_LENGTH}: length={termLength}

What it means

LogBufferDescriptor.checkTermLength enforces Aeron's allowed term-buffer size range: below TERM_MIN_LENGTH (64KB) a term buffer cannot implement the log buffer protocol correctly, so an IllegalStateException is thrown. It is a configuration sanity check applied whenever a term length is set or a log is created.

Solutions

Raise the term length to at least LogBufferDescriptor.TERM_MIN_LENGTH (65536 bytes).
Use Aeron's named constants: Context.publicationTermLength(TERM_MIN_LENGTH) or property aeron.term.buffer.length=64k.
If memory is a concern, keep the minimum term length and reduce via other means (sparse files via aeron.term.buffer.sparse=true).

Example fix

// before
ctx.publicationTermLength(32 * 1024); // too small
// after
ctx.publicationTermLength(LogBufferDescriptor.TERM_MIN_LENGTH); // 65536

Defensive patterns

Strategy: validation

Validate before calling

if (termLength < LogBufferDescriptor.TERM_MIN_LENGTH || termLength > LogBufferDescriptor.TERM_MAX_LENGTH) { throw new IllegalArgumentException("termLength out of range"); }

Try / catch

try { LogBufferDescriptor.checkTermLength(termLength); ctx.publicationTermLength(termLength); } catch (IllegalStateException e) { /* clamp to TERM_MIN_LENGTH */ }

Prevention

Use TERM_MIN_LENGTH/TERM_MAX_LENGTH constants, not magic numbers
Remember 64k notation in aeron.term.buffer.length
Don't copy term-length configs from other systems
If memory constrained, use sparse term buffers instead of smaller lengths

When it happens

Trigger: Setting Context/publication termLength (or system property aeron.term.buffer.length) below 64KB, e.g. to 32KB or 4096, before creating a publication or image.

Common situations: Trying to shrink memory footprint for embedded/CI environments with an unsupported small value, copying a config from another messaging library, or mistaking KB for bytes (e.g. 64 instead of 65536).

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

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

Appendix: source

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

        LOG_META_DATA_LENGTH = PAGE_MIN_SIZE;
    }

    private LogBufferDescriptor()
    {
    }

    /**
     * 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.
     *

View on GitHub (pinned to 6d60124e15)