aeron-io/aeron · error · IllegalArgumentException

params must be used as a complete set: initialTermId termId…

Error message

params must be used as a complete set: initialTermId termId termOffset channel=<channelUri>

What it means

The optional subscription position params (initial-term-id, term-id, term-offset) must be supplied together as a complete set. If at least one is present on the channel URI but fewer than all three, the driver throws IllegalArgumentException. These params let a subscriber join a specific position; a partial set is ambiguous.

Solutions

1. Include all three params (initial-term-id, term-id, term-offset) in the URI.
2. Omit all three if you do not need an explicit join position.
3. Build the URI from a helper that adds the trio atomically.

Example fix

// before
"aeron:udp?endpoint=localhost:40456|initial-term-id=0|term-id=1"
// after
"aeron:udp?endpoint=localhost:40456|initial-term-id=0|term-id=1|term-offset=0"

int count = 0;
for (String p : new String[]{"initial-term-id", "term-id", "term-offset"})
    if (uriContains(uri, p)) count++;
if (count != 0 && count != 3) throw new IllegalArgumentException("initial-term-id, term-id, term-offset must all be set together");

When it happens

Trigger: Adding a subscription with a URI containing only one or two of: initial-term-id, term-id, term-offset, e.g. aeron:udp?...|initial-term-id=0|term-id=1 without term-offset.

Common situations: Hand-editing URIs to replay from a position and forgetting one param; code that appends params conditionally and skips a null/absent one.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• value exceeds maximum permitted: value=
• must be a number
• invalid entity tag, must be a number
• tag is reserved: channel=
• termOffset= out of range: channel=

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

Appendix: source

Thrown at aeron-driver/src/main/java/io/aeron/driver/SubscriptionParams.java:79

            params.isResponse = true;
        }

        int count = 0;

        final String initialTermIdStr = channelUri.get(INITIAL_TERM_ID_PARAM_NAME);
        count = initialTermIdStr != null ? count + 1 : count;

        final String termIdStr = channelUri.get(TERM_ID_PARAM_NAME);
        count = termIdStr != null ? count + 1 : count;

        final String termOffsetStr = channelUri.get(TERM_OFFSET_PARAM_NAME);
        count = termOffsetStr != null ? count + 1 : count;

        if (count > 0)
        {
            if (count < 3)
            {
                throw new IllegalArgumentException("params must be used as a complete set: " +
                    INITIAL_TERM_ID_PARAM_NAME + " " +
                    TERM_ID_PARAM_NAME + " " +
                    TERM_OFFSET_PARAM_NAME + " channel=" + channelUri);
            }

            params.initialTermId = Integer.parseInt(initialTermIdStr);
            params.termId = Integer.parseInt(termIdStr);
            params.termOffset = Integer.parseInt(termOffsetStr);

            if (params.termOffset < 0 || params.termOffset > LogBufferDescriptor.TERM_MAX_LENGTH)
            {
                throw new IllegalArgumentException(
                    TERM_OFFSET_PARAM_NAME + "=" + params.termOffset + " out of range: channel=" + channelUri);
            }

            if (!FrameDescriptor.isFrameAligned(params.termOffset))
            {
                throw new IllegalArgumentException(

View on GitHub (pinned to 6d60124e15)