{"record":{"id":"eeca0f9512d1e96d","repo":"aeron-io/aeron","slug":"formatmatcherror-term-offset-param-name-existingtermoffset","errorCode":null,"errorMessage":"formatMatchError(TERM_OFFSET_PARAM_NAME, existingTermOffset, params.termOffset, existingChannel, channelUri)","messagePattern":"formatMatchError\\(TERM_OFFSET_PARAM_NAME, existingTermOffset, params\\.termOffset, existingChannel, channelUri\\)","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"aeron-driver/src/main/java/io/aeron/driver/PublicationParams.java","lineNumber":361,"sourceCode":"                String.valueOf(existingTermId),\n                String.valueOf(params.termId),\n                existingChannel,\n                channelUri.toString()));\n        }\n\n        if (channelUri.containsKey(TERM_OFFSET_PARAM_NAME) && params.termOffset != existingTermOffset)\n        {\n            throw new IllegalStateException(formatMatchError(\n                TERM_OFFSET_PARAM_NAME,\n                String.valueOf(existingTermOffset),\n                String.valueOf(params.termOffset),\n                existingChannel,\n                channelUri.toString()));\n        }\n    }\n\n    static void validateSpiesSimulateConnection(\n        final PublicationParams params,\n        final boolean existingSpiesSimulateConnection,\n        final String channel,\n        final String existingChannel)\n    {\n        if (params.spiesSimulateConnection != existingSpiesSimulateConnection)\n        {\n            throw new IllegalStateException(\"existing publication has different spiesSimulateConnection: existing=\" +\n                existingSpiesSimulateConnection + \" requested=\" + params.spiesSimulateConnection +\n                \" existingChannel=\" + existingChannel + \" channel=\" + channel);\n        }\n    }\n\n    static void validateMtuForSndbuf(\n        final PublicationParams params,\n        final int channelSocketSndbufLength,\n        final MediaDriver.Context ctx,\n        final String channel,\n        final String existingChannel)","sourceCodeStart":343,"sourceCodeEnd":379,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-driver/src/main/java/io/aeron/driver/PublicationParams.java#L343-L379","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nctx.spiesSimulateConnection(false); // existing publication created with true\n\n// after\nctx.spiesSimulateConnection(true);","handlingStrategy":"try-catch","validationCode":"boolean flag = ChannelUri.parse(channel).getBoolean(\"spies-simulate-connection\", ctx.spiesSimulateConnection());\nif (flag != existingSpiesSimulateConnection) {\n    throw new IllegalArgumentException(\"spies-simulate-connection=\" + flag + \" conflicts with existing publication \" + existingSpiesSimulateConnection);\n}","typeGuard":null,"tryCatchPattern":"try {\n    pub = aeron.addPublication(channel, streamId);\n} catch (IllegalStateException e) {\n    if (e.getMessage().startsWith(\"existing publication has different spiesSimulateConnection\")) {\n        throw new PublicationMismatchException(\"spies-simulate-connection differs\", e);\n    }\n    throw e;\n}","preventionTips":["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"],"tags":["aeron","publication-reuse","spies-simulate-connection","ipc","state-conflict"],"backgroundTag":"conflicting-config-options","analyzedSha":"6d60124e15e35c11b49ba2e3c2c2858a09a18803","analyzedAt":"2026-09-12T11:17:07.683Z","contentChangedAt":"2026-09-12T11:17:07.683Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}