aeron-io/aeron · error · IllegalArgumentException

term length more than max length of

Error message

term length more than max length of ${TERM_MAX_LENGTH}: value=${value}

What it means

ChannelUriStringBuilder.termLength(String) parses the 'term-length' URI parameter and throws IllegalArgumentException when the parsed size exceeds TERM_MAX_LENGTH (1GB, Integer.MAX_VALUE). Aeron term buffers are indexed by int, so a term length above 2^31-1 cannot be represented. The throw is a fail-fast guard preventing an impossible buffer size from reaching the media driver.

Solutions

1. Reduce the term-length value in the URI to at most 1g (1073741824); use 1g if you need the maximum
2. Check for unit typos: '2g' should likely be '1g', '64m', etc.
3. Call the Integer/int overload termLength(int) so the compiler rejects out-of-range values at compile time where possible

Example fix

// before
builder.termLength("2g"); // throws
// after
builder.termLength("1g"); // max allowed

long value = parseSize("term-length", termLengthValue);
if (value > Integer.MAX_VALUE) throw new IllegalArgumentException("term-length must be <= 1g: " + value);

try { builder.termLength(str); } catch (IllegalArgumentException e) { log.error("bad term-length: {}", e.getMessage()); }

When it happens

Trigger: Calling termLength(String) with a value string that parses to more than 1073741824 (1g), e.g. ChannelUri.addStaticId-style URIs containing term-length=2g, or calling the String overload instead of the Integer overload with an oversized value.

Common situations: Hand-written Aeron channel URIs with a mistaken 'g' suffix or unit (term-length=2g instead of 1g); copying channel configs between systems where a larger term length was used; typos where bytes were intended but a multiple-of-GB value was written.

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 offset not in range 0-1g
• invalid position= < 0
• 'initial-term-id' must be a valid integer
• 'term-id' must be a valid integer
• term offset not multiple of FRAME_ALIGNMENT

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

Appendix: source

Thrown at aeron-client/src/main/java/io/aeron/ChannelUriStringBuilder.java:700

     *
     * @param channelUri to read the value from.
     * @return this for a fluent API.
     * @see CommonContext#TERM_LENGTH_PARAM_NAME
     */
    public ChannelUriStringBuilder termLength(final ChannelUri channelUri)
    {
        final String termLengthValue = channelUri.get(TERM_LENGTH_PARAM_NAME);
        if (null == termLengthValue)
        {
            termLength = null;
            return this;
        }
        else
        {
            final long value = parseSize(TERM_LENGTH_PARAM_NAME, termLengthValue);
            if (value > Integer.MAX_VALUE)
            {
                throw new IllegalArgumentException(
                    "term length more than max length of " + TERM_MAX_LENGTH + ": value=" + value);
            }

            return termLength((int)value);
        }
    }

    /**
     * Get the length of buffer used for each term of the log.
     *
     * @return the length of buffer used for each term of the log.
     * @see CommonContext#TERM_LENGTH_PARAM_NAME
     */
    public Integer termLength()
    {
        return termLength;
    }

View on GitHub (pinned to 6d60124e15)