{"record":{"id":"c8a37e9ee332028d","repo":"aeron-io/aeron","slug":"mtu-length-explicitmtulength-does-not-match-session-id-tag","errorCode":null,"errorMessage":"mtu-length={explicitMtuLength} does not match session-id tag value: channel={channelUri}","messagePattern":"mtu-length=(.+?) does not match session-id tag value: channel=(.+?)","errorType":"validation","errorClass":"InvalidChannelException","httpStatus":null,"severity":"error","filePath":"aeron-driver/src/main/java/io/aeron/driver/PublicationParams.java","lineNumber":270,"sourceCode":"    }\n\n    static void validateTermLength(\n        final PublicationParams params, final int explicitTermLength, final ChannelUri channelUri)\n    {\n        if (params.isSessionIdTagged && explicitTermLength != params.termLength)\n        {\n            throw new InvalidChannelException(\n                TERM_LENGTH_PARAM_NAME + \"=\" + explicitTermLength + \" does not match session-id tag value: channel=\" +\n                channelUri);\n        }\n    }\n\n    static void validateMtuLength(\n        final PublicationParams params, final int explicitMtuLength, final ChannelUri channelUri)\n    {\n        if (params.isSessionIdTagged && explicitMtuLength != params.mtuLength)\n        {\n            throw new InvalidChannelException(\n                MTU_LENGTH_PARAM_NAME + \"=\" + explicitMtuLength + \" does not match session-id tag value: channel=\" +\n                channelUri);\n        }\n    }\n\n    private static String formatMatchError(\n        final String paramName,\n        final String existingValue,\n        final String newValue,\n        final String existingChannelUri,\n        final String newChannelUri)\n    {\n        return \"existing publication has different '\" + paramName + \"': existing=\" +\n            existingValue + \" requested=\" + newValue + \" existingChannel=\" + existingChannelUri +\n            \" channel=\" + newChannelUri;\n    }\n\n    static void confirmMatch(","sourceCodeStart":252,"sourceCodeEnd":288,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-driver/src/main/java/io/aeron/driver/PublicationParams.java#L252-L288","documentation":"Same conflict as the term-length case but for mtu-length: with a tagged session-id, the MTU is inherited from the tagged log buffer, and an explicit mtu-length URI parameter that differs from the tagged value makes PublicationParams.validateMtuLength throw InvalidChannelException.","triggerScenarios":"addPublication/addExclusivePublication with a channel URI containing session-id=tag:N plus an mtu-length parameter whose value differs from the MTU recorded for that tag, e.g. \"...|session-id=tag:100|mtu-length=8k\" while the tag resolves mtu-length=16k.","commonSituations":"Mixing tagged-session reuse with MTU tuning; template URIs that always append mtu-length; changing MTU policy for one stream without updating the tag source.","solutions":["Drop the explicit mtu-length parameter so the tagged value is used.","Align the explicit mtu-length exactly with the MTU stored under the session-id tag.","Use an untagged session-id if you genuinely need a different MTU for this stream.","Centralize URI construction so tagged sessions never receive per-parameter overrides."],"exampleFix":"// before\n\"aeron:udp?endpoint=localhost:40456|session-id=tag:100|mtu-length=8k\"\n\n// after\n\"aeron:udp?endpoint=localhost:40456|session-id=tag:100\"","handlingStrategy":"validation","validationCode":"ChannelUri uri = ChannelUri.parse(channel);\nString sessionId = uri.get(\"session-id\");\nString mtuLength = uri.get(\"mtu-length\");\nif (sessionId != null && sessionId.startsWith(\"tag:\") && mtuLength != null) {\n    throw new IllegalArgumentException(\"Do not set mtu-length explicitly on tagged-session channel: \" + channel);\n}","typeGuard":null,"tryCatchPattern":"try {\n    pub = aeron.addPublication(channel, streamId);\n} catch (InvalidChannelException e) {\n    if (e.getMessage().contains(\"mtu-length=\" ) && e.getMessage().contains(\"session-id tag\")) {\n        channel = stripParam(channel, \"mtu-length\");\n        pub = aeron.addPublication(channel, streamId);\n    } else throw e;\n}","preventionTips":["Treat tagged-session URIs as fully derived: no per-param overrides","Document tag inheritance rules next to URI templates","Test URI construction with a unit test asserting no overrides on tag:N sessions"],"tags":["aeron","configuration","mtu-length","session-id","tagged-session"],"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"}