{"record":{"id":"bfc820dfc82e2fc1","repo":"aeron-io/aeron","slug":"mtu-greater-than-max-message-length-for-term-length-mtu","errorCode":null,"errorMessage":"MTU greater than max message length for term length: mtu={mtuLength} maxMessageLength={maxMessageLength} termLength={termLength} channel={channelUri}","messagePattern":"MTU greater than max message length for term length: mtu=(.+?) maxMessageLength=(.+?) termLength=(.+?) channel=(.+?)","errorType":"validation","errorClass":"InvalidChannelException","httpStatus":null,"severity":"error","filePath":"aeron-driver/src/main/java/io/aeron/driver/PublicationParams.java","lineNumber":248,"sourceCode":"            this.termLength = termLength;\n        }\n    }\n\n    private void getMtuLength(final ChannelUri channelUri)\n    {\n        final String mtuParam = channelUri.get(MTU_LENGTH_PARAM_NAME);\n        if (null != mtuParam)\n        {\n            final int mtuLength = (int)SystemUtil.parseSize(MTU_LENGTH_PARAM_NAME, mtuParam);\n            Configuration.validateMtuLength(mtuLength);\n            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)","sourceCodeStart":230,"sourceCodeEnd":266,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-driver/src/main/java/io/aeron/driver/PublicationParams.java#L230-L266","documentation":"Aeron rejects a publication/subscription channel whose mtu-length exceeds the maximum message length derivable from the term buffer length (FrameDescriptor.computeMaxMessageLength, termLength minus framing header space). The driver throws InvalidChannelException in PublicationParams.getMtuLength because fragments larger than what a term buffer can frame could never be delivered. MTU must be <= maxMessageLength and is also typically a multiple of FrameDescriptor.FRAGMENT_ALIGNMENT (32).","triggerScenarios":"Adding a publication or exclusive publication where the channel URI sets mtu-length (or the context default) larger than computeMaxMessageLength(term-length), e.g. mtu-length=16384 with term-length=16384, or a huge mtu-length like 1Mb with the default 64Kb term length.","commonSituations":"Copy-pasting an mtu-length from another transport config; setting term-length and mtu-length to the same value forgetting header overhead; tuning for throughput by raising MTU without raising term-length; Aeron-specific gotcha since MTU also must fit UDP datagram limits.","solutions":["Lower the mtu-length URI parameter so it is <= computeMaxMessageLength(term-length) (termLength - 32, aligned to 32 bytes).","Increase term-length to at least mtu + framing overhead (e.g. mtu-length=16384 requires term-length of at least 64K in practice).","Remove the explicit mtu-length parameter and let the driver default (ctx.publicationTermWindowLength / defaultMtuLength) apply.","If the values come from code, validate with AeronThread-safe checks before addPublication: FrameDescriptor.computeMaxMessageLength(termLength) >= mtuLength."],"exampleFix":"// before\nAeron.connect().addPublication(\"aeron:udp?endpoint=224.0.1.1:40456|term-length=64k|mtu-length=128k\", 1);\n\n// after (mtu fits within term length)\nAeron.connect().addPublication(\"aeron:udp?endpoint=224.0.1.1:40456|term-length=64k|mtu-length=16k\", 1);","handlingStrategy":"validation","validationCode":"import static io.aeron.logbuffer.FrameDescriptor.computeMaxMessageLength;\n\nvoid checkMtu(int mtuLength, int termLength) {\n    int max = computeMaxMessageLength(termLength);\n    if (mtuLength > max) {\n        throw new IllegalArgumentException(\"mtu-length=\" + mtuLength + \" exceeds maxMessageLength=\" + max + \" for term-length=\" + termLength);\n    }\n}","typeGuard":null,"tryCatchPattern":"try {\n    publication = aeron.addPublication(channel, streamId);\n} catch (InvalidChannelException e) {\n    log.error(\"Rejecting channel config: {}\", e.getMessage());\n    throw new ConfigException(channel, e);\n}","preventionTips":["Always validate mtu-length <= termLength - 32 before building the URI","Keep mtu-length a multiple of 32 (FRAGMENT_ALIGNMENT)","Prefer driver defaults unless benchmarking showed a win","Centralize term-length/mtu-length pairs in one config constant"],"tags":["aeron","configuration","mtu","term-length","invalid-channel"],"backgroundTag":"invalid-config-value","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"}