{"record":{"id":"01bfe2b7af478e95","repo":"aeron-io/aeron","slug":"mtu-not-a-multiple-of-frame-alignment-mtu-mtu","errorCode":null,"errorMessage":"MTU not a multiple of FRAME_ALIGNMENT: mtu=${mtu}","messagePattern":"MTU not a multiple of FRAME_ALIGNMENT: mtu=(.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"aeron-client/src/main/java/io/aeron/ChannelUriStringBuilder.java","lineNumber":615,"sourceCode":"     * Set the maximum transmission unit (MTU) including Aeron header for a datagram payload. If this is greater\n     * than the network MTU for UDP then the packet will be fragmented and can amplify the impact of loss.\n     *\n     * @param mtu the maximum transmission unit including Aeron header for a datagram payload.\n     * @return this for a fluent API.\n     * @see CommonContext#MTU_LENGTH_PARAM_NAME\n     */\n    public ChannelUriStringBuilder mtu(final Integer mtu)\n    {\n        if (null != mtu)\n        {\n            if (mtu < 32 || mtu > 65504)\n            {\n                throw new IllegalArgumentException(\"MTU not in range 32-65504: \" + mtu);\n            }\n\n            if ((mtu & (FRAME_ALIGNMENT - 1)) != 0)\n            {\n                throw new IllegalArgumentException(\"MTU not a multiple of FRAME_ALIGNMENT: mtu=\" + mtu);\n            }\n        }\n\n        this.mtu = mtu;\n        return this;\n    }\n\n    /**\n     * Set the mtu value to be what is in the {@link ChannelUri} which may be null.\n     *\n     * @param channelUri to read the value from.\n     * @return this for a fluent API.\n     * @see CommonContext#MTU_LENGTH_PARAM_NAME\n     */\n    public ChannelUriStringBuilder mtu(final ChannelUri channelUri)\n    {\n        final String mtuValue = channelUri.get(MTU_LENGTH_PARAM_NAME);\n        if (null == mtuValue)","sourceCodeStart":597,"sourceCodeEnd":633,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-client/src/main/java/io/aeron/ChannelUriStringBuilder.java#L597-L633","documentation":"Thrown by ChannelUriStringBuilder.mtu(Integer) when the MTU is not a multiple of FRAME_ALIGNMENT (32 bytes). Aeron messages are written in 32-byte-aligned frames, so an unaligned MTU would break framing on the term buffer.","triggerScenarios":"builder.mtu(1500) or builder.mtu(9000) — both not divisible by 32 — while within the 32-65504 range.","commonSituations":"Copying the NIC's IP MTU (1500) or jumbo frame size (9000) directly into Aeron's MTU without aligning; tuning guides that quote network MTU rather than Aeron MTU.","solutions":["Round the MTU down/up to a multiple of 32, e.g. (mtu / FRAME_ALIGNMENT) * FRAME_ALIGNMENT.","Use standard aligned values like 4096, 8192, 16384, or 65504.","For a 1500-byte network path use 1408 (44 * 32) or similar aligned value below the IP MTU."],"exampleFix":"// before\nbuilder.mtu(1500);\n// after\nbuilder.mtu(1408); // multiple of FRAME_ALIGNMENT (32)","handlingStrategy":"validation","validationCode":"if (mtu != null && (mtu & (FrameDescriptor.FRAME_ALIGNMENT - 1)) != 0) { throw new IllegalArgumentException(\"MTU must be a multiple of 32\"); }","typeGuard":"boolean isAlignedMtu(Integer mtu) { return mtu == null || (mtu & 31) == 0; }","tryCatchPattern":"try { builder.mtu(m); } catch (IllegalArgumentException e) { builder.mtu((m / 32) * 32); }","preventionTips":["Never copy NIC IP MTU (1500/9000) directly; round to a multiple of 32","Use 1408 for 1500-byte networks","Centralize MTU selection in one validated config function"],"tags":["aeron","channel-uri","mtu","alignment"],"backgroundTag":"invalid-argument-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"}