aeron-io/aeron · error · InvalidChannelException

term-length= does not match session-id tag value: channel=

Error message

term-length={explicitTermLength} does not match session-id tag value: channel={channelUri}

What it means

When a channel URI uses a tagged session (session-id of the form tag:N, meaning parameters are inherited from a previously created tagged log buffer), the driver resolves term-length from the tag. If an explicit term-length URI parameter is also present and differs from the tagged value, PublicationParams.validateTermLength throws InvalidChannelException because the explicit and inherited parameters contradict each other.

Solutions

  1. Remove the explicit term-length parameter from the URI so it is inherited from the tagged session.
  2. Set term-length to exactly match the value recorded for the session-id tag.
  3. Use a plain (non-tagged) session-id if you want the explicit term-length to take effect independently.
  4. Check where the URI is assembled and only emit term-length when session-id is not tag:N.

Example fix

// before
"aeron:udp?endpoint=localhost:40456|session-id=tag:100|term-length=128k" // tag holds 64k

// after
"aeron:udp?endpoint=localhost:40456|session-id=tag:100"
Defensive patterns

Strategy: validation

Validate before calling

ChannelUri uri = ChannelUri.parse(channel);
String sessionId = uri.get("session-id");
String termLength = uri.get("term-length");
if (sessionId != null && sessionId.startsWith("tag:") && termLength != null) {
    throw new IllegalArgumentException("Do not set term-length explicitly on tagged-session channel: " + channel);
}

Try / catch

try {
    pub = aeron.addPublication(channel, streamId);
} catch (InvalidChannelException e) {
    if (e.getMessage().contains("does not match session-id tag")) {
        channel = stripParam(channel, "term-length");
        pub = aeron.addPublication(channel, streamId);
    } else throw e;
}

Prevention

When it happens

Trigger: addPublication/addExclusivePublication with a channel containing both a tagged session-id (e.g. session-id=tag:100) and an explicit term-length that does not equal the term length recorded under that tag, e.g. "aeron:udp?endpoint=host:40456|session-id=tag:100|term-length=128k" while the tagged entity has 64k.

Common situations: Building URIs programmatically where session-id is tagged but a hardcoded term-length slips in; reusing a URI template with term-length after switching to session tagging; two teams coordinating parameters via tags but drifting on term length.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

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

Appendix: source

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

            validateMtuLength(this, mtuLength, channelUri);
            this.mtuLength = mtuLength;
        }

        final int maxMessageLength = FrameDescriptor.computeMaxMessageLength(termLength);
        if (mtuLength > maxMessageLength)
        {
            throw new InvalidChannelException("MTU greater than max message length for term length: mtu=" +
                mtuLength + " maxMessageLength=" + maxMessageLength + " termLength=" + termLength + " channel=" +
                channelUri);
        }
    }

    static void validateTermLength(
        final PublicationParams params, final int explicitTermLength, final ChannelUri channelUri)
    {
        if (params.isSessionIdTagged && explicitTermLength != params.termLength)
        {
            throw new InvalidChannelException(
                TERM_LENGTH_PARAM_NAME + "=" + explicitTermLength + " does not match session-id tag value: channel=" +
                channelUri);
        }
    }

    static void validateMtuLength(
        final PublicationParams params, final int explicitMtuLength, final ChannelUri channelUri)
    {
        if (params.isSessionIdTagged && explicitMtuLength != params.mtuLength)
        {
            throw new InvalidChannelException(
                MTU_LENGTH_PARAM_NAME + "=" + explicitMtuLength + " does not match session-id tag value: channel=" +
                channelUri);
        }
    }

    private static String formatMatchError(
        final String paramName,

View on GitHub (pinned to 6d60124e15)