aeron-io/aeron · error · IllegalStateException

formatMatchError(paramName, existingValue, paramsValue…

Error message

formatMatchError(paramName, existingValue, paramsValue, existingChannel, channelUri)

What it means

This is the session-id branch of PublicationParams.confirmMatch: when the new channel URI explicitly sets session-id and the requested params.sessionId differs from the existing publication's sessionId, an IllegalStateException is thrown with the standardized 'existing publication has different ...' message built by formatMatchError. Publication reuse must preserve the session.

Solutions

Match the session-id to the existing publication's value (shown in the error as existing=...).
Remove the explicit session-id parameter so the check is skipped and the driver assigns/reuses the existing session.
If different sessions are intended, accept that a new publication (and new log buffer) will be created — verify stream/session pairing is actually what you want.
Log and diff the two URIs printed in the error to find where they diverge.

Example fix

// before
aeron.addPublication("aeron:udp?endpoint=localhost:40456|session-id=2002", 1001); // existing is 1001

// after
aeron.addPublication("aeron:udp?endpoint=localhost:40456|session-id=1001", 1001);

Defensive patterns

Strategy: try-catch

Validate before calling

String sid = ChannelUri.parse(channel).get("session-id");
if (sid != null && !sid.startsWith("tag:") && existingSessionId != Integer.parseInt(sid)) {
    throw new IllegalArgumentException("session-id " + sid + " conflicts with existing publication session " + existingSessionId);
}

Try / catch

try {
    pub = aeron.addPublication(channel, streamId);
} catch (IllegalStateException e) {
    if (e.getMessage().startsWith("existing publication has different 'session-id'")) {
        throw new PublicationMismatchException("Session id differs from live publication", e);
    }
    throw e;
}

Prevention

Only set session-id explicitly when you own session allocation for the stream
Keep session-id assignment in a single allocator module
Log both URIs from the error when debugging reuse conflicts

When it happens

Trigger: addPublication with URI session-id=X where an existing publication for the same channel was registered with session-id=Y (X != Y). Usually indicates the URIs don't actually denote the same publication despite matching endpoint/stream.

Common situations: Using fixed session-id=0 or a random session-id in one code path and an explicit one in another; load-balanced publishers sharing an endpoint but each forcing different session ids; URI templates substituting session ids dynamically.

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/797978052a779921. Report an issue: GitHub.

Appendix: source

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

                String.valueOf(mtuLength),
                String.valueOf(params.mtuLength),
                existingChannel,
                channelUri.toString()));
        }

        if (channelUri.containsKey(TERM_LENGTH_PARAM_NAME) && rawLog.termLength() != params.termLength)
        {
            throw new IllegalStateException(formatMatchError(
                TERM_LENGTH_PARAM_NAME,
                String.valueOf(rawLog.termLength()),
                String.valueOf(params.termLength),
                existingChannel,
                channelUri.toString()));
        }

        if (channelUri.containsKey(SESSION_ID_PARAM_NAME) && params.sessionId != existingSessionId)
        {
            throw new IllegalStateException(formatMatchError(
                SESSION_ID_PARAM_NAME,
                String.valueOf(existingSessionId),
                String.valueOf(params.sessionId),
                existingChannel,
                channelUri.toString()));
        }

        if (channelUri.containsKey(INITIAL_TERM_ID_PARAM_NAME) && params.initialTermId != existingInitialTermId)
        {
            throw new IllegalStateException(formatMatchError(
                INITIAL_TERM_ID_PARAM_NAME,
                String.valueOf(existingInitialTermId),
                String.valueOf(params.initialTermId),
                existingChannel,
                channelUri.toString()));
        }

        if (channelUri.containsKey(TERM_ID_PARAM_NAME) && params.termId != existingTermId)

View on GitHub (pinned to 6d60124e15)