{"record":{"id":"f9068ed4947ab9eb","repo":"aeron-io/aeron","slug":"mtulength-mtulength-max-udp-payload-length-max-udp-payload","errorCode":null,"errorMessage":"mtuLength=${mtuLength} > MAX_UDP_PAYLOAD_LENGTH=${MAX_UDP_PAYLOAD_LENGTH}","messagePattern":"mtuLength=(.+?) > MAX_UDP_PAYLOAD_LENGTH=(.+?)","errorType":"validation","errorClass":"ConfigurationException","httpStatus":null,"severity":"error","filePath":"aeron-driver/src/main/java/io/aeron/driver/Configuration.java","lineNumber":2457,"sourceCode":"\n    /**\n     * Validate that the MTU is an appropriate length. MTU lengths must be a multiple of\n     * {@link FrameDescriptor#FRAME_ALIGNMENT}.\n     *\n     * @param mtuLength to be validated.\n     * @throws ConfigurationException if the MTU length is not valid.\n     */\n    public static void validateMtuLength(final int mtuLength)\n    {\n        if (mtuLength <= DataHeaderFlyweight.HEADER_LENGTH)\n        {\n            throw new ConfigurationException(\n                \"mtuLength=\" + mtuLength + \" <= HEADER_LENGTH=\" + DataHeaderFlyweight.HEADER_LENGTH);\n        }\n\n        if (mtuLength > MAX_UDP_PAYLOAD_LENGTH)\n        {\n            throw new ConfigurationException(\n                \"mtuLength=\" + mtuLength + \" > MAX_UDP_PAYLOAD_LENGTH=\" + MAX_UDP_PAYLOAD_LENGTH);\n        }\n\n        if (!FrameDescriptor.isFrameAligned(mtuLength))\n        {\n            throw new ConfigurationException(\n                \"mtuLength=\" + mtuLength + \" is not a multiple of FRAME_ALIGNMENT=\" + FrameDescriptor.FRAME_ALIGNMENT);\n        }\n    }\n\n    /**\n     * Get the {@link TerminationValidator} implementations which can be used for validating a termination request\n     * sent to the driver to ensure the client has the right to terminate a driver.\n     *\n     * @return the {@link TerminationValidator}\n     */\n    public static TerminationValidator terminationValidator()\n    {","sourceCodeStart":2439,"sourceCodeEnd":2475,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-driver/src/main/java/io/aeron/driver/Configuration.java#L2439-L2475","documentation":"Configuration.validateMtuLength also caps the MTU at MAX_UDP_PAYLOAD_LENGTH (65507 bytes), the largest payload a UDP datagram can carry on IP networks. Requesting a larger MTU would produce datagrams that cannot be sent, so the driver rejects it upfront.","triggerScenarios":"Calling validateMtuLength with mtuLength > 65507, e.g. setting aeron.mtu.length=131072 or an mtu= URI parameter copied from a TCP/tuned value.","commonSituations":"Confusing MTU with term-buffer size and setting huge values, jumbo-frame experiments pushed beyond the UDP limit, or misconfigured URIs sharing one big number across settings.","solutions":["Reduce the MTU to <= 65507 (and typically <= 65527 minus header for practical networks, e.g. 16384)","Use a supported value like 1408, 4096, or 8192 for normal deployments","Ensure the MTU is also frame-aligned to the required 32-byte boundary (next check in the same validator)"],"exampleFix":"// before\nctx.mtuLength(131072);\n// after\nctx.mtuLength(65504);","handlingStrategy":"validation","validationCode":"int mtu = Integer.getInteger(\"aeron.mtu.length\", 1408);\nif (mtu > Configuration.MAX_UDP_PAYLOAD_LENGTH) { mtu = Configuration.MAX_UDP_PAYLOAD_LENGTH; }","typeGuard":"boolean isValidMtu(int mtu) { return mtu > DataHeaderFlyweight.HEADER_LENGTH && mtu <= Configuration.MAX_UDP_PAYLOAD_LENGTH && FrameDescriptor.isFrameAligned(mtu); }","tryCatchPattern":"try { mediaDriver.launch(ctx); } catch (ConfigurationException e) { log.fatal(\"mtu too large: \" + e.getMessage()); System.exit(1); }","preventionTips":["Cap MTU at 65507 (UDP max payload); prefer typical values like 1408-16384","Do not copy TCP/tuned large values into aeron.mtu.length","Distinguish MTU from term-buffer length in config templates"],"tags":["aeron-driver","configuration","mtu","udp"],"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"}