aeron-io/aeron · error · InvalidChannelException

params must be used as a complete set: initial-term-id…

Error message

params must be used as a complete set: initial-term-id term-id term-offset channel={channelUri}

What it means

Aeron's initial-term-id, term-id and term-offset URI parameters must either all be absent or all present; they jointly pin a publication's start position. Supplying only some of the three makes the position under-specified, so an InvalidChannelException is thrown.

Solutions

  1. Add all three params (initial-term-id, term-id, term-offset) to the channel URI
  2. Remove all of them if position pinning is not intended
  3. Build the URI programmatically with ChannelUri and set the full param triple

Example fix

// before
"aeron:udp?endpoint=224.0.1.1:40456|termId=0"
// after
"aeron:udp?endpoint=224.0.1.1:40456|initial-term-id=0|term-id=0|term-offset=0"
Defensive patterns

Strategy: validation

Validate before calling

int n = 0; for (String p : new String[]{"initial-term-id","term-id","term-offset"}) if (uri.contains(p)) n++; if (n > 0 && n < 3) throw new IllegalArgumentException("position params must be complete");

Try / catch

try { pub = aeron.addPublication(uri, streamId); } catch (InvalidChannelException e) { log.error("bad channel params: {}", e.getMessage()); }

Prevention

When it happens

Trigger: Adding one or two of @initialTermId, termId, termOffset to a publication channel URI (e.g. only termId=0) when subscribing/adding the publication via Aeron.addPublication or client with those params.

Common situations: Hand-editing channel URIs for position-pinned publications; partial parameter propagation from config templates; mixing an old URI with new params when reproducing a session across restarts.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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

Appendix: source

Thrown at aeron-driver/src/main/java/io/aeron/driver/PublicationParams.java:117

        params.getUntetheredRestingTimeout(channelUri, ctx);
        params.getMaxResend(channelUri, ctx);

        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 InvalidChannelException("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 = parseInt(initialTermIdStr, INITIAL_TERM_ID_PARAM_NAME);
            params.termId = parseInt(termIdStr, TERM_ID_PARAM_NAME);
            params.termOffset = parseInt(termOffsetStr, TERM_OFFSET_PARAM_NAME);

            if (params.termOffset > params.termLength)
            {
                throw new InvalidChannelException(
                    TERM_OFFSET_PARAM_NAME + "=" + params.termOffset + " > " +
                    TERM_LENGTH_PARAM_NAME + "=" + params.termLength + ": channel=" + channelUri);
            }

            if (params.termOffset < 0 || params.termOffset > LogBufferDescriptor.TERM_MAX_LENGTH)
            {
                throw new InvalidChannelException(

View on GitHub (pinned to 6d60124e15)