aeron-io/aeron · error · IllegalStateException

formatMatchError(TERM_ID_PARAM_NAME, existingTermId…

Error message

formatMatchError(TERM_ID_PARAM_NAME, existingTermId, params.termId, existingChannel, channelUri)

What it means

term-offset branch of confirmMatch: when the channel URI explicitly includes term-offset and the requested value differs from the existing publication's term offset, PublicationParams.confirmMatch throws IllegalStateException. Term offset is live position state and must match for the reuse path to succeed.

Solutions

  1. Remove term-offset from the URI; it is runtime state, not configuration.
  2. Match the existing= offset shown in the error message.
  3. Close the existing publication before adding with a specific term-offset.
  4. Strip dynamic params (term-id, term-offset, session-id unless deliberate) when persisting URIs.

Example fix

// before
"aeron:udp?endpoint=localhost:40456|term-offset=4096" // existing at 0

// after
"aeron:udp?endpoint=localhost:40456"
Defensive patterns

Strategy: validation

Validate before calling

String toff = ChannelUri.parse(channel).get("term-offset");
if (toff != null) {
    throw new IllegalArgumentException("term-offset is dynamic state; remove it from channel URI: " + channel);
}

Try / catch

try {
    pub = aeron.addPublication(channel, streamId);
} catch (IllegalStateException e) {
    if (e.getMessage().startsWith("existing publication has different 'term-offset'")) {
        channel = stripParam(channel, "term-offset");
        pub = aeron.addPublication(channel, streamId);
    } else throw e;
}

Prevention

When it happens

Trigger: addPublication with URI term-offset=X against an existing publication whose position has advanced to offset Y; typical when reusing recorded URIs that embedded term-offset.

Common situations: Snapshot/replay tooling that bakes term-offset into the channel string; hand-edited URIs copying params from a media driver listing.

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

Appendix: source

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

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

        if (channelUri.containsKey(TERM_ID_PARAM_NAME) && params.termId != existingTermId)
        {
            throw new IllegalStateException(formatMatchError(
                TERM_ID_PARAM_NAME,
                String.valueOf(existingTermId),
                String.valueOf(params.termId),
                existingChannel,
                channelUri.toString()));
        }

        if (channelUri.containsKey(TERM_OFFSET_PARAM_NAME) && params.termOffset != existingTermOffset)
        {
            throw new IllegalStateException(formatMatchError(
                TERM_OFFSET_PARAM_NAME,
                String.valueOf(existingTermOffset),
                String.valueOf(params.termOffset),
                existingChannel,
                channelUri.toString()));
        }
    }

    static void validateSpiesSimulateConnection(
        final PublicationParams params,
        final boolean existingSpiesSimulateConnection,
        final String channel,
        final String existingChannel)
    {
        if (params.spiesSimulateConnection != existingSpiesSimulateConnection)
        {
            throw new IllegalStateException("existing publication has different spiesSimulateConnection: existing=" +
                existingSpiesSimulateConnection + " requested=" + params.spiesSimulateConnection +

View on GitHub (pinned to 6d60124e15)