{"record":{"id":"e402e9fca98b9759","repo":"aeron-io/aeron","slug":"mtu-not-in-range-32-65504-mtu","errorCode":null,"errorMessage":"MTU not in range 32-65504: ${mtu}","messagePattern":"MTU not in range 32-65504: (.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"aeron-client/src/main/java/io/aeron/ChannelUriStringBuilder.java","lineNumber":610,"sourceCode":"    {\n        return ttl;\n    }\n\n    /**\n     * 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","sourceCodeStart":592,"sourceCodeEnd":628,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-client/src/main/java/io/aeron/ChannelUriStringBuilder.java#L592-L628","documentation":"Thrown by ChannelUriStringBuilder.mtu(Integer) when the MTU is below 32 or above 65504. MTU bounds follow Aeron's frame size constraints (max payload of 65504 = 64KB minus headers, min 32 aligned bytes), and violating them would produce frames the network or driver cannot carry.","triggerScenarios":"builder.mtu(16), builder.mtu(90000), or passing a jumbo value larger than the 64KB frame limit.","commonSituations":"Confusing IP MTU (1500/9000) with Aeron MTU and setting 65536+; tuning for jumbo frames beyond the frame header limit; accidental 0 or negative config values.","solutions":["Set MTU within [32, 65504]; typical values are 4096, 8192, 16384, or 65504 for max throughput.","Clamp config-provided values: Math.min(65504, Math.max(32, v)).","Ensure MTU is a multiple of FRAME_ALIGNMENT (32) to avoid the follow-on alignment error."],"exampleFix":"// before\nbuilder.mtu(65536);\n// after\nbuilder.mtu(65504);","handlingStrategy":"validation","validationCode":"if (mtu != null && (mtu < 32 || mtu > 65504)) { throw new IllegalArgumentException(\"MTU not in range 32-65504: \" + mtu); }","typeGuard":"boolean isValidMtu(Integer mtu) { return mtu == null || (mtu >= 32 && mtu <= 65504 && (mtu & 31) == 0); }","tryCatchPattern":"try { builder.mtu(m); } catch (IllegalArgumentException e) { builder.mtu(4096); }","preventionTips":["Clamp MTU config to [32, 65504] at load time","Remember Aeron MTU includes headers and caps at 65504, not 65536","Prefer standard aligned sizes: 4096/8192/16384/65504"],"tags":["aeron","channel-uri","network","mtu"],"backgroundTag":"value-out-of-range","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"}