{"record":{"id":"a89760e1b836eb28","repo":"aeron-io/aeron","slug":"formatmatcherror-term-id-param-name-existingtermid-params","errorCode":null,"errorMessage":"formatMatchError(TERM_ID_PARAM_NAME, existingTermId, params.termId, existingChannel, channelUri)","messagePattern":"formatMatchError\\(TERM_ID_PARAM_NAME, existingTermId, params\\.termId, existingChannel, channelUri\\)","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"aeron-driver/src/main/java/io/aeron/driver/PublicationParams.java","lineNumber":351,"sourceCode":"                String.valueOf(existingInitialTermId),\n                String.valueOf(params.initialTermId),\n                existingChannel,\n                channelUri.toString()));\n        }\n\n        if (channelUri.containsKey(TERM_ID_PARAM_NAME) && params.termId != existingTermId)\n        {\n            throw new IllegalStateException(formatMatchError(\n                TERM_ID_PARAM_NAME,\n                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 +","sourceCodeStart":333,"sourceCodeEnd":369,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-driver/src/main/java/io/aeron/driver/PublicationParams.java#L333-L369","documentation":"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.","triggerScenarios":"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.","commonSituations":"Snapshot/replay tooling that bakes term-offset into the channel string; hand-edited URIs copying params from a media driver listing.","solutions":["Remove term-offset from the URI; it is runtime state, not configuration.","Match the existing= offset shown in the error message.","Close the existing publication before adding with a specific term-offset.","Strip dynamic params (term-id, term-offset, session-id unless deliberate) when persisting URIs."],"exampleFix":"// before\n\"aeron:udp?endpoint=localhost:40456|term-offset=4096\" // existing at 0\n\n// after\n\"aeron:udp?endpoint=localhost:40456\"","handlingStrategy":"validation","validationCode":"String toff = ChannelUri.parse(channel).get(\"term-offset\");\nif (toff != null) {\n    throw new IllegalArgumentException(\"term-offset is dynamic state; remove it from channel URI: \" + channel);\n}","typeGuard":null,"tryCatchPattern":"try {\n    pub = aeron.addPublication(channel, streamId);\n} catch (IllegalStateException e) {\n    if (e.getMessage().startsWith(\"existing publication has different 'term-offset'\")) {\n        channel = stripParam(channel, \"term-offset\");\n        pub = aeron.addPublication(channel, streamId);\n    } else throw e;\n}","preventionTips":["Never bake term-offset into stored URIs","Sanitize URIs captured from snapshots/replay tooling before reusing them","Keep a fixed param list for persisted channel strings"],"tags":["aeron","publication-reuse","term-offset","channel-uri","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"}