{"record":{"id":"c3772146cae14df1","repo":"aeron-io/aeron","slug":"mtulength-mtulength-is-not-a-multiple-of-frame-alignment","errorCode":null,"errorMessage":"mtuLength=${mtuLength} is not a multiple of FRAME_ALIGNMENT=${FrameDescriptor.FRAME_ALIGNMENT}","messagePattern":"mtuLength=(.+?) is not a multiple of FRAME_ALIGNMENT=(.+?)","errorType":"validation","errorClass":"ConfigurationException","httpStatus":null,"severity":"error","filePath":"aeron-driver/src/main/java/io/aeron/driver/Configuration.java","lineNumber":2463,"sourceCode":"     * @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    {\n        TerminationValidator validator = null;\n        try\n        {\n            final String className = getProperty(TERMINATION_VALIDATOR_PROP_NAME);\n            if (null == className)\n            {","sourceCodeStart":2445,"sourceCodeEnd":2481,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-driver/src/main/java/io/aeron/driver/Configuration.java#L2445-L2481","documentation":"Aeron's MTU length must be a multiple of FRAME_ALIGNMENT (32 bytes) so that every term buffer frame write stays aligned, which is required for correct record framing and concurrent readers. Configuration.validateMtuLength throws this ConfigurationException during driver/media context validation when the configured mtuLength fails FrameDescriptor.isFrameAlignment check. The driver refuses to start with a misaligned MTU rather than corrupting the log buffer.","triggerScenarios":"Calling Configuration.validateMtuLength(mtuLength) (via DriverContext/Media.Context.conclude) with an mtuLength that is not a multiple of FrameDescriptor.FRAME_ALIGNMENT (32), e.g. setting aeron.mtu.length=1000 or 4000.","commonSituations":"Tuning MTU to match network path MTU (e.g. 1500, 9000) without rounding to a 32-byte multiple; copying recommended values from other messaging systems; typos like 65501 instead of 65507-aligned values.","solutions":["Set aeron.mtu.length (or context.mtuLength) to a multiple of 32, e.g. 4096, 8192, or 16384","Use FrameDescriptor.alignTerm or round the desired value: mtuLength = (mtuLength + 31) & ~31","If following network MTU advice, pick the largest multiple of 32 that fits (e.g. 8948 for jumbo frames, 1500 -> 1472-ish payloads)","If it must remain non-aligned for protocol reasons, re-raise on the Aeron mailing list, but the alignment is a hard invariant"],"exampleFix":"// before\nctx.mtuLength(9000);\n// after\nctx.mtuLength(8948); // 8948 = 279 * 32, aligned","handlingStrategy":"validation","validationCode":"import static io.aeron.driver.Configuration.validateMtuLength;\nint mtuLength = Integer.getInteger(\"aeron.mtu.length\", 4096);\nif ((mtuLength & (io.aeron.protocol.DataHeaderFlyweight.FRAME_ALIGNMENT - 1)) != 0) {\n    mtuLength = (mtuLength + 31) & ~31; // round up to multiple of 32\n}\nvalidateMtuLength(mtuLength);","typeGuard":null,"tryCatchPattern":"try {\n    ctx.mtuLength(requested);\n    ctx.conclude();\n} catch (ConfigurationException e) {\n    // fall back to a known-good aligned default\n    ctx.mtuLength(4096);\n    ctx.conclude();\n}","preventionTips":["Always round MTU values with BitUtil.findNextPositivePowerOfTwo or (v + 31) & ~31 before setting","Prefer standard MTU sizes: 4096, 8192, 16384","Add a startup unit test that concludes the driver context with production config values"],"tags":["aeron","configuration","mtu","alignment"],"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"}