{"record":{"id":"c903062bea39f4e5","repo":"aeron-io/aeron","slug":"formatmatcherror-initial-term-id-param-name","errorCode":null,"errorMessage":"formatMatchError(INITIAL_TERM_ID_PARAM_NAME, existingInitialTermId, params.initialTermId, existingChannel, channelUri)","messagePattern":"formatMatchError\\(INITIAL_TERM_ID_PARAM_NAME, existingInitialTermId, params\\.initialTermId, existingChannel, channelUri\\)","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"aeron-driver/src/main/java/io/aeron/driver/PublicationParams.java","lineNumber":341,"sourceCode":"                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)\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","sourceCodeStart":323,"sourceCodeEnd":359,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-driver/src/main/java/io/aeron/driver/PublicationParams.java#L323-L359","documentation":"term-id branch of confirmMatch: when the URI explicitly sets term-id and it differs from the existing publication's current term id, PublicationParams.confirmMatch throws IllegalStateException. Term id tracks the active term buffer position and must match on publication reuse.","triggerScenarios":"addPublication with URI term-id=X against an existing publication currently at term-id=Y; common when replaying or re-attaching with captured URIs that embedded a stale term-id.","commonSituations":"Persisted channel URIs that recorded term-id at snapshot time, later reused after the publication advanced; automation tooling that serializes all params including term-id.","solutions":["Remove term-id from the URI — it is dynamic state, not a stable config parameter.","Match the current term-id reported in the error message.","Close the existing publication first if you truly need a fresh term-id.","Whitelist which URI params you serialize (endpoint, stream-id, static params only)."],"exampleFix":"// before\n\"aeron:udp?endpoint=localhost:40456|term-id=7\" // existing is now at 9\n\n// after\n\"aeron:udp?endpoint=localhost:40456\" // let driver manage term-id","handlingStrategy":"validation","validationCode":"String tid = ChannelUri.parse(channel).get(\"term-id\");\nif (tid != null) {\n    throw new IllegalArgumentException(\"term-id 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-id'\")) {\n        channel = stripParam(channel, \"term-id\");\n        pub = aeron.addPublication(channel, streamId);\n    } else throw e;\n}","preventionTips":["Never persist term-id in URIs; it changes as the publication advances","Whitelist static params when serializing channels","Strip term-id/term-offset when copying URIs from driver tooling"],"tags":["aeron","publication-reuse","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"}