aeron-io/aeron · error · IllegalStateException

formatMatchError(TERM_OFFSET_PARAM_NAME…

Error message

formatMatchError(TERM_OFFSET_PARAM_NAME, existingTermOffset, params.termOffset, existingChannel, channelUri)

What it means

PublicationParams.validateSpiesSimulateConnection throws IllegalStateException when a publication being re-added (or a spy subscribing to an exclusive publication's channel) requests a spies-simulate-connection value that differs from the existing publication. The spies-simulate-connection flag controls whether spy subscriptions behave as if a connection exists, and Aeron requires it to be consistent across reuse of the same log buffer.

Solutions

Align the spies-simulate-connection setting with the existing publication (see existing= in the message).
Set spies-simulate-connection=true in the MediaDriver.Context / channel for all users of the stream.
Close the existing publication and recreate it with the desired flag.
Standardize the flag across the organization's Aeron context defaults to avoid mixed additions.

Example fix

// before
ctx.spiesSimulateConnection(false); // existing publication created with true

// after
ctx.spiesSimulateConnection(true);

Defensive patterns

Strategy: try-catch

Validate before calling

boolean flag = ChannelUri.parse(channel).getBoolean("spies-simulate-connection", ctx.spiesSimulateConnection());
if (flag != existingSpiesSimulateConnection) {
    throw new IllegalArgumentException("spies-simulate-connection=" + flag + " conflicts with existing publication " + existingSpiesSimulateConnection);
}

Try / catch

try {
    pub = aeron.addPublication(channel, streamId);
} catch (IllegalStateException e) {
    if (e.getMessage().startsWith("existing publication has different spiesSimulateConnection")) {
        throw new PublicationMismatchException("spies-simulate-connection differs", e);
    }
    throw e;
}

Prevention

Set spies-simulate-connection uniformly in the shared MediaDriver context
Enable it globally if any spy/IPC subscribers exist on the stream
Document the flag as stream-wide, not per-client

When it happens

Trigger: Adding a publication or spy subscription on a channel URI with spies-simulate-connection=true (or via context Publication.spiesSimulateConnection) while the existing publication on that channel/session was created with the opposite setting.

Common situations: Spy (IPC) subscribers added after a network publication with default spies-simulate-connection=false; one process enabling the flag for lower-latency local taps while the original publisher disabled it; differing Aeron contexts between app instances sharing a driver.

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

Appendix: source

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

                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 +
                " existingChannel=" + existingChannel + " channel=" + channel);
        }
    }

    static void validateMtuForSndbuf(
        final PublicationParams params,
        final int channelSocketSndbufLength,
        final MediaDriver.Context ctx,
        final String channel,
        final String existingChannel)

View on GitHub (pinned to 6d60124e15)