aeron-io/aeron · error · IllegalArgumentException

termOffset= > termLength=

Error message

termOffset=${termOffset} > termLength=${termLength}

What it means

Thrown by ChannelUriStringBuilder.validate() when termOffset is set and exceeds the configured termLength. A term offset must point within the term buffer, so an offset greater than the term length would address outside the buffer and cannot produce a valid channel URI.

Solutions

1. Increase termLength (typically to a power of 2 like 1MB, 16MB) so it is >= termOffset.
2. Reduce termOffset to a value within [0, termLength).
3. Drop explicit termLength and let the builder/driver pick the default.

Example fix

// before
builder.termLength(1 << 16).termOffset(1 << 20).validate();
// after
builder.termLength(1 << 24).termOffset(1 << 20).validate();

if (termLength != null && termOffset != null && termOffset > termLength) { throw new IllegalArgumentException("termOffset must be <= termLength"); }

boolean offsetWithinTerm(Integer termLength, Integer termOffset) { return termLength == null || termOffset == null || termOffset <= termLength; }

try { uri = builder.validate().build(); } catch (IllegalArgumentException e) { log.warn("invalid term params", e); uri = defaultBuilder.build(); }

When it happens

Trigger: Calling validate() with builder.termLength(64*1024).termOffset(100*1024), or deriving termOffset from a position whose low bits exceed the chosen termLength (e.g. termLength smaller than the position's modulo).

Common situations: Setting an initialPosition whose offset component exceeds a hand-set termLength; mixing parameters copied from a URI with a different term length (e.g. 64k term length but offset from a 1MB-term recording).

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

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

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

Appendix: source

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

        final boolean anyNonNull = null != initialTermId || null != termId || null != termOffset;
        final boolean anyNull = null == initialTermId || null == termId || null == termOffset;
        if (anyNonNull)
        {
            if (anyNull)
            {
                throw new IllegalArgumentException(
                    "either all or none of the parameters ['initialTermId', 'termId', 'termOffset'] must be provided");
            }

            if (termId - initialTermId < 0)
            {
                throw new IllegalArgumentException(
                    "difference greater than 2^31 - 1: termId=" + termId + " - initialTermId=" + initialTermId);
            }

            if (null != termLength && termOffset > termLength)
            {
                throw new IllegalArgumentException("termOffset=" + termOffset + " > termLength=" + termLength);
            }
        }

        return this;
    }

    /**
     * Set the prefix for taking an additional action such as spying on an outgoing publication with "aeron-spy".
     *
     * @param prefix to be applied to the URI before the scheme.
     * @return this for a fluent API.
     * @see ChannelUri#SPY_QUALIFIER
     */
    public ChannelUriStringBuilder prefix(final String prefix)
    {
        if (null != prefix && !prefix.isEmpty() && !prefix.equals(SPY_QUALIFIER))
        {
            throw new IllegalArgumentException("invalid prefix: " + prefix);

View on GitHub (pinned to 6d60124e15)