aeron-io/aeron · error · ConfigurationException

mtuLength= <= HEADER_LENGTH=

Error message

mtuLength=${mtuLength} <= HEADER_LENGTH=${DataHeaderFlyweight.HEADER_LENGTH}

What it means

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.

Solutions

1. Set MTU to a realistic value above 32 bytes, e.g. 1408 (Ethernet) or 8192/65507 as appropriate
2. Remove the aeron.mtu.length override to use the default (1408)
3. Validate any computed MTU against DataHeaderFlyweight.HEADER_LENGTH before configuring

Example fix

// before
ctx.mtuLength(32);
// after
ctx.mtuLength(1408);

int mtu = ctx.mtuLength();
if (mtu <= DataHeaderFlyweight.HEADER_LENGTH || mtu > Configuration.MAX_UDP_PAYLOAD_LENGTH || !FrameDescriptor.isFrameAligned(mtu)) {
    ctx.mtuLength(1408);
}

boolean isValidMtu(int mtu) { return mtu > DataHeaderFlyweight.HEADER_LENGTH && mtu <= Configuration.MAX_UDP_PAYLOAD_LENGTH && FrameDescriptor.isFrameAligned(mtu); }

try { mediaDriver.launch(ctx); } catch (ConfigurationException e) { log.fatal("invalid mtu: " + e.getMessage()); System.exit(1); }

When it happens

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

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

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• mtuLength= > initialWindowLength=
• mtuLength= > MAX_UDP_PAYLOAD_LENGTH=
• untetheredLingerTimeoutNs=
• less than min size of
• greater than max size of

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

Appendix: source

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

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

    /**
     * Validate that the MTU is an appropriate length. MTU lengths must be a multiple of
     * {@link FrameDescriptor#FRAME_ALIGNMENT}.
     *
     * @param mtuLength to be validated.
     * @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

View on GitHub (pinned to 6d60124e15)