aeron-io/aeron · error · ConfigurationException

mtuLength= is not a multiple of FRAME_ALIGNMENT=

Error message

mtuLength=${mtuLength} is not a multiple of FRAME_ALIGNMENT=${FrameDescriptor.FRAME_ALIGNMENT}

What it means

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.

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

Example fix

// before
ctx.mtuLength(9000);
// after
ctx.mtuLength(8948); // 8948 = 279 * 32, aligned

Defensive patterns

Strategy: validation

Validate before calling

import static io.aeron.driver.Configuration.validateMtuLength;
int mtuLength = Integer.getInteger("aeron.mtu.length", 4096);
if ((mtuLength & (io.aeron.protocol.DataHeaderFlyweight.FRAME_ALIGNMENT - 1)) != 0) {
    mtuLength = (mtuLength + 31) & ~31; // round up to multiple of 32
}
validateMtuLength(mtuLength);

Try / catch

try {
    ctx.mtuLength(requested);
    ctx.conclude();
} catch (ConfigurationException e) {
    // fall back to a known-good aligned default
    ctx.mtuLength(4096);
    ctx.conclude();
}

Prevention

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

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

AI-assisted analysis of aeron-io/aeron@6d60124e15 (2026-09-12). Data as JSON: /api/errors/c3772146cae14df1. Report an issue: GitHub.

Appendix: source

Thrown at aeron-driver/src/main/java/io/aeron/driver/Configuration.java:2463

     * @throws ConfigurationException if the MTU length is not valid.
     */
    public static void validateMtuLength(final int mtuLength)
    {
        if (mtuLength <= DataHeaderFlyweight.HEADER_LENGTH)
        {
            throw new ConfigurationException(
                "mtuLength=" + mtuLength + " <= HEADER_LENGTH=" + DataHeaderFlyweight.HEADER_LENGTH);
        }

        if (mtuLength > MAX_UDP_PAYLOAD_LENGTH)
        {
            throw new ConfigurationException(
                "mtuLength=" + mtuLength + " > MAX_UDP_PAYLOAD_LENGTH=" + MAX_UDP_PAYLOAD_LENGTH);
        }

        if (!FrameDescriptor.isFrameAligned(mtuLength))
        {
            throw new ConfigurationException(
                "mtuLength=" + mtuLength + " is not a multiple of FRAME_ALIGNMENT=" + FrameDescriptor.FRAME_ALIGNMENT);
        }
    }

    /**
     * Get the {@link TerminationValidator} implementations which can be used for validating a termination request
     * sent to the driver to ensure the client has the right to terminate a driver.
     *
     * @return the {@link TerminationValidator}
     */
    public static TerminationValidator terminationValidator()
    {
        TerminationValidator validator = null;
        try
        {
            final String className = getProperty(TERMINATION_VALIDATOR_PROP_NAME);
            if (null == className)
            {

View on GitHub (pinned to 6d60124e15)