{"record":{"id":"6ac48af94f2e3d38","repo":"aeron-io/aeron","slug":"term-length-explicittermlength-does-not-match-session-id-tag","errorCode":null,"errorMessage":"term-length={explicitTermLength} does not match session-id tag value: channel={channelUri}","messagePattern":"term-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":259,"sourceCode":"            validateMtuLength(this, mtuLength, channelUri);\n            this.mtuLength = mtuLength;\n        }\n\n        final int maxMessageLength = FrameDescriptor.computeMaxMessageLength(termLength);\n        if (mtuLength > maxMessageLength)\n        {\n            throw new InvalidChannelException(\"MTU greater than max message length for term length: mtu=\" +\n                mtuLength + \" maxMessageLength=\" + maxMessageLength + \" termLength=\" + termLength + \" channel=\" +\n                channelUri);\n        }\n    }\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,","sourceCodeStart":241,"sourceCodeEnd":277,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-driver/src/main/java/io/aeron/driver/PublicationParams.java#L241-L277","documentation":"When a channel URI uses a tagged session (session-id of the form tag:N, meaning parameters are inherited from a previously created tagged log buffer), the driver resolves term-length from the tag. If an explicit term-length URI parameter is also present and differs from the tagged value, PublicationParams.validateTermLength throws InvalidChannelException because the explicit and inherited parameters contradict each other.","triggerScenarios":"addPublication/addExclusivePublication with a channel containing both a tagged session-id (e.g. session-id=tag:100) and an explicit term-length that does not equal the term length recorded under that tag, e.g. \"aeron:udp?endpoint=host:40456|session-id=tag:100|term-length=128k\" while the tagged entity has 64k.","commonSituations":"Building URIs programmatically where session-id is tagged but a hardcoded term-length slips in; reusing a URI template with term-length after switching to session tagging; two teams coordinating parameters via tags but drifting on term length.","solutions":["Remove the explicit term-length parameter from the URI so it is inherited from the tagged session.","Set term-length to exactly match the value recorded for the session-id tag.","Use a plain (non-tagged) session-id if you want the explicit term-length to take effect independently.","Check where the URI is assembled and only emit term-length when session-id is not tag:N."],"exampleFix":"// before\n\"aeron:udp?endpoint=localhost:40456|session-id=tag:100|term-length=128k\" // tag holds 64k\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 termLength = uri.get(\"term-length\");\nif (sessionId != null && sessionId.startsWith(\"tag:\") && termLength != null) {\n    throw new IllegalArgumentException(\"Do not set term-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(\"does not match session-id tag\")) {\n        channel = stripParam(channel, \"term-length\");\n        pub = aeron.addPublication(channel, streamId);\n    } else throw e;\n}","preventionTips":["Never append term-length to URIs whose session-id is tag:N","Build URIs via a builder that knows which params are inherited from tags","Keep tag source-of-truth config in one module"],"tags":["aeron","configuration","term-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"}