{"record":{"id":"8b548f53082389e3","repo":"aeron-io/aeron","slug":"formatmatcherror-session-id-param-name-existingsessionid","errorCode":null,"errorMessage":"formatMatchError(SESSION_ID_PARAM_NAME, existingSessionId, params.sessionId, existingChannel, channelUri)","messagePattern":"formatMatchError\\(SESSION_ID_PARAM_NAME, existingSessionId, params\\.sessionId, existingChannel, channelUri\\)","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"aeron-driver/src/main/java/io/aeron/driver/PublicationParams.java","lineNumber":331,"sourceCode":"                String.valueOf(rawLog.termLength()),\n                String.valueOf(params.termLength),\n                existingChannel,\n                channelUri.toString()));\n        }\n\n        if (channelUri.containsKey(SESSION_ID_PARAM_NAME) && params.sessionId != existingSessionId)\n        {\n            throw new IllegalStateException(formatMatchError(\n                SESSION_ID_PARAM_NAME,\n                String.valueOf(existingSessionId),\n                String.valueOf(params.sessionId),\n                existingChannel,\n                channelUri.toString()));\n        }\n\n        if (channelUri.containsKey(INITIAL_TERM_ID_PARAM_NAME) && params.initialTermId != existingInitialTermId)\n        {\n            throw new IllegalStateException(formatMatchError(\n                INITIAL_TERM_ID_PARAM_NAME,\n                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)","sourceCodeStart":313,"sourceCodeEnd":349,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-driver/src/main/java/io/aeron/driver/PublicationParams.java#L313-L349","documentation":"initial-term-id branch of confirmMatch: when the channel URI explicitly includes initial-term-id and the requested value differs from the existing publication's initial term id stored in its log buffer metadata, PublicationParams.confirmMatch throws IllegalStateException. Initial term id pins where the term counter starts and cannot change on reuse.","triggerScenarios":"Re-adding a publication with URI initial-term-id=X while the existing log buffer was built with initial-term-id=Y; typically happens with deterministic/replayable publisher setups that hardcode initial-term-id differently across processes.","commonSituations":"Recording/replay systems that set initial-term-id per run; crash-restart code generating a new initial-term-id while the old publication is still registered; two app instances using the same deterministic channel config but different seeds.","solutions":["Use the same initial-term-id as the existing publication (see existing= in the message).","Remove initial-term-id from the URI so the existing buffer's value is accepted.","Ensure the prior publication is fully closed before adding with a new initial-term-id.","Persist the chosen initial-term-id (e.g. in a ledger) so restarts reuse it rather than generating a fresh value."],"exampleFix":"// before\n\"aeron:udp?endpoint=localhost:40456|initial-term-id=-42\" // existing buffer has 0\n\n// after\n\"aeron:udp?endpoint=localhost:40456|initial-term-id=0\"","handlingStrategy":"try-catch","validationCode":"String iti = ChannelUri.parse(channel).get(\"initial-term-id\");\nif (iti != null && existingInitialTermId != Long.decode(iti)) {\n    throw new IllegalArgumentException(\"initial-term-id \" + iti + \" conflicts with existing publication \" + existingInitialTermId);\n}","typeGuard":null,"tryCatchPattern":"try {\n    pub = aeron.addPublication(channel, streamId);\n} catch (IllegalStateException e) {\n    if (e.getMessage().startsWith(\"existing publication has different 'initial-term-id'\")) {\n        throw new PublicationMismatchException(\"Initial term id differs\", e);\n    }\n    throw e;\n}","preventionTips":["Persist initial-term-id across restarts if determinism is required","Omit initial-term-id unless replay/deterministic setup demands it","Derive it from the same seed/config on all instances sharing a stream"],"tags":["aeron","publication-reuse","initial-term-id","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"}