aeron-io/aeron · error · IllegalArgumentException

either all or none of the parameters ['initialTermId'…

Error message

either all or none of the parameters ['initialTermId', 'termId', 'termOffset'] must be provided

What it means

The positioning triple initialTermId, termId, termOffset must be supplied either completely or not at all; validate() throws IllegalArgumentException when only a subset is set. Additionally, when all are provided, termId must be within 2^31-1 of initialTermId.

Solutions

Set all three params (initialTermId, termId, termOffset) together, or none of them
When reconstructing from a recording, read all three from the same source atomically
Validate ordering: termId must be >= initialTermId and within 2^31-1; guard with (termId - initialTermId) >= 0 before validating

Example fix

// before
builder.initialTermId(0).termOffset(1024).validate(); // missing termId
// after
builder.initialTermId(0).termId(1).termOffset(1024).validate();

Defensive patterns

Strategy: validation

Validate before calling

static void requireCompletePositioning(Long initialTermId, Long termId, Long termOffset) {
    boolean any = initialTermId != null || termId != null || termOffset != null;
    boolean all = initialTermId != null && termId != null && termOffset != null;
    if (any && !all) throw new IllegalArgumentException("set all or none of initialTermId/termId/termOffset");
    if (all && termId - initialTermId < 0) throw new IllegalArgumentException("termId < initialTermId");
}

Type guard

static boolean positioningComplete(Long i, Long t, Long o) {
    return (i == null && t == null && o == null) || (i != null && t != null && o != null);
}

Try / catch

try {
    builder.validate().build();
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("either all or none of the parameters")) {
        throw new IllegalArgumentException("Positioning params must be set together: initialTermId, termId, termOffset", e);
    }
    throw e;
}

Prevention

Always set initialTermId, termId, and termOffset as a group from a single source (e.g. recording catalog)
Wrap arithmetic in long and check (termId - initialTermId) >= 0 to catch wraparound before validating
Omit all positioning params unless you specifically need a replay position — the defaults are usually correct

When it happens

Trigger: Calling validate() with e.g. .initialTermId(x).termId(y) but no .termOffset(...) (anyNonNull && anyNull), or with termId < initialTermId so the difference is negative ("difference greater than 2^31 - 1" companion check).

Common situations: Replaying/recording code that restores a subset of the positioning params (e.g. only termOffset) from a catalog or config; integer-underflow when termId wrapped past initialTermId in long-running streams.

Related errors

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

Appendix: source

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

    public ChannelUriStringBuilder validate()
    {
        if (null == media)
        {
            throw new IllegalArgumentException("media type is mandatory");
        }

        if (CommonContext.UDP_MEDIA.equals(media) && (null == endpoint && null == controlEndpoint))
        {
            throw new IllegalArgumentException("either 'endpoint' or 'control' must be specified for UDP.");
        }

        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;
    }

View on GitHub (pinned to 6d60124e15)