{"record":{"id":"e5b648323af5ef1f","repo":"aeron-io/aeron","slug":"mtulength-mtulength-header-length-dataheaderflyweight-header","errorCode":null,"errorMessage":"mtuLength=${mtuLength} <= HEADER_LENGTH=${DataHeaderFlyweight.HEADER_LENGTH}","messagePattern":"mtuLength=(.+?) <= HEADER_LENGTH=(.+?)","errorType":"validation","errorClass":"ConfigurationException","httpStatus":null,"severity":"error","filePath":"aeron-driver/src/main/java/io/aeron/driver/Configuration.java","lineNumber":2451,"sourceCode":"        if (mtuLength > initialWindowLength)\n        {\n            throw new ConfigurationException(\n                \"mtuLength=\" + mtuLength + \" > initialWindowLength=\" + initialWindowLength);\n        }\n    }\n\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","sourceCodeStart":2433,"sourceCodeEnd":2469,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-driver/src/main/java/io/aeron/driver/Configuration.java#L2433-L2469","documentation":"Configuration.validateMtuLength requires the MTU to be strictly larger than DataHeaderFlyweight.HEADER_LENGTH (32 bytes), because every datagram must be able to carry at least one data frame plus its header. An MTU at or below the header size cannot carry any payload, so the driver rejects it at configuration time.","triggerScenarios":"Calling validateMtuLength(mtuLength) (via driver or publication setup) with a value <= 32, e.g. mtuLength=32 or mtuLength=0 from a mistyped aeron.mtu.length property or channel URI.","commonSituations":"Unit confusion (bytes vs some other unit) when setting mtu in a URI, misreading the property as a header/payload size, or programmatic defaults accidentally zeroed.","solutions":["Set MTU to a realistic value above 32 bytes, e.g. 1408 (Ethernet) or 8192/65507 as appropriate","Remove the aeron.mtu.length override to use the default (1408)","Validate any computed MTU against DataHeaderFlyweight.HEADER_LENGTH before configuring"],"exampleFix":"// before\nctx.mtuLength(32);\n// after\nctx.mtuLength(1408);","handlingStrategy":"validation","validationCode":"int mtu = ctx.mtuLength();\nif (mtu <= DataHeaderFlyweight.HEADER_LENGTH || mtu > Configuration.MAX_UDP_PAYLOAD_LENGTH || !FrameDescriptor.isFrameAligned(mtu)) {\n    ctx.mtuLength(1408);\n}","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(\"invalid mtu: \" + e.getMessage()); System.exit(1); }","preventionTips":["Always specify MTU in bytes and keep it > 32","Keep MTU frame-aligned (multiple of 32)","Sanity-check computed or env-sourced MTU values before launch"],"tags":["aeron-driver","configuration","mtu","validation"],"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"}