aeron-io/aeron · error · InvalidChannelException

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

Error message

mtu-length={explicitMtuLength} does not match session-id tag value: channel={channelUri}

What it means

Same conflict as the term-length case but for mtu-length: with a tagged session-id, the MTU is inherited from the tagged log buffer, and an explicit mtu-length URI parameter that differs from the tagged value makes PublicationParams.validateMtuLength throw InvalidChannelException.

Solutions

1. Drop the explicit mtu-length parameter so the tagged value is used.
2. Align the explicit mtu-length exactly with the MTU stored under the session-id tag.
3. Use an untagged session-id if you genuinely need a different MTU for this stream.
4. Centralize URI construction so tagged sessions never receive per-parameter overrides.

Example fix

// before
"aeron:udp?endpoint=localhost:40456|session-id=tag:100|mtu-length=8k"

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

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

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

When it happens

Trigger: addPublication/addExclusivePublication with a channel URI containing session-id=tag:N plus an mtu-length parameter whose value differs from the MTU recorded for that tag, e.g. "...|session-id=tag:100|mtu-length=8k" while the tag resolves mtu-length=16k.

Common situations: Mixing tagged-session reuse with MTU tuning; template URIs that always append mtu-length; changing MTU policy for one stream without updating the tag source.

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

• term-length= does not match session-id tag value: channel=
• low session id value
• reserved session range too large
• Aeron client instance must set…
• Aeron client must use a RethrowingErrorHandler

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

Appendix: source

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

    }

    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,
        final String existingValue,
        final String newValue,
        final String existingChannelUri,
        final String newChannelUri)
    {
        return "existing publication has different '" + paramName + "': existing=" +
            existingValue + " requested=" + newValue + " existingChannel=" + existingChannelUri +
            " channel=" + newChannelUri;
    }

    static void confirmMatch(

View on GitHub (pinned to 6d60124e15)