{"record":{"id":"797978052a779921","repo":"aeron-io/aeron","slug":"formatmatcherror-paramname-existingvalue-paramsvalue","errorCode":null,"errorMessage":"formatMatchError(paramName, existingValue, paramsValue, existingChannel, channelUri)","messagePattern":"formatMatchError\\(paramName, existingValue, paramsValue, existingChannel, channelUri\\)","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"aeron-driver/src/main/java/io/aeron/driver/PublicationParams.java","lineNumber":321,"sourceCode":"                String.valueOf(mtuLength),\n                String.valueOf(params.mtuLength),\n                existingChannel,\n                channelUri.toString()));\n        }\n\n        if (channelUri.containsKey(TERM_LENGTH_PARAM_NAME) && rawLog.termLength() != params.termLength)\n        {\n            throw new IllegalStateException(formatMatchError(\n                TERM_LENGTH_PARAM_NAME,\n                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)","sourceCodeStart":303,"sourceCodeEnd":339,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-driver/src/main/java/io/aeron/driver/PublicationParams.java#L303-L339","documentation":"This is the session-id branch of PublicationParams.confirmMatch: when the new channel URI explicitly sets session-id and the requested params.sessionId differs from the existing publication's sessionId, an IllegalStateException is thrown with the standardized 'existing publication has different ...' message built by formatMatchError. Publication reuse must preserve the session.","triggerScenarios":"addPublication with URI session-id=X where an existing publication for the same channel was registered with session-id=Y (X != Y). Usually indicates the URIs don't actually denote the same publication despite matching endpoint/stream.","commonSituations":"Using fixed session-id=0 or a random session-id in one code path and an explicit one in another; load-balanced publishers sharing an endpoint but each forcing different session ids; URI templates substituting session ids dynamically.","solutions":["Match the session-id to the existing publication's value (shown in the error as existing=...).","Remove the explicit session-id parameter so the check is skipped and the driver assigns/reuses the existing session.","If different sessions are intended, accept that a new publication (and new log buffer) will be created — verify stream/session pairing is actually what you want.","Log and diff the two URIs printed in the error to find where they diverge."],"exampleFix":"// before\naeron.addPublication(\"aeron:udp?endpoint=localhost:40456|session-id=2002\", 1001); // existing is 1001\n\n// after\naeron.addPublication(\"aeron:udp?endpoint=localhost:40456|session-id=1001\", 1001);","handlingStrategy":"try-catch","validationCode":"String sid = ChannelUri.parse(channel).get(\"session-id\");\nif (sid != null && !sid.startsWith(\"tag:\") && existingSessionId != Integer.parseInt(sid)) {\n    throw new IllegalArgumentException(\"session-id \" + sid + \" conflicts with existing publication session \" + existingSessionId);\n}","typeGuard":null,"tryCatchPattern":"try {\n    pub = aeron.addPublication(channel, streamId);\n} catch (IllegalStateException e) {\n    if (e.getMessage().startsWith(\"existing publication has different 'session-id'\")) {\n        throw new PublicationMismatchException(\"Session id differs from live publication\", e);\n    }\n    throw e;\n}","preventionTips":["Only set session-id explicitly when you own session allocation for the stream","Keep session-id assignment in a single allocator module","Log both URIs from the error when debugging reuse conflicts"],"tags":["aeron","publication-reuse","session-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"}