aeron-io/aeron · error · ConfigurationException

mtuLength= > MAX_UDP_PAYLOAD_LENGTH=

Error message

mtuLength=${mtuLength} > MAX_UDP_PAYLOAD_LENGTH=${MAX_UDP_PAYLOAD_LENGTH}

What it means

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.

Solutions

1. Reduce the MTU to <= 65507 (and typically <= 65527 minus header for practical networks, e.g. 16384)
2. Use a supported value like 1408, 4096, or 8192 for normal deployments
3. Ensure the MTU is also frame-aligned to the required 32-byte boundary (next check in the same validator)

Example fix

// before
ctx.mtuLength(131072);
// after
ctx.mtuLength(65504);

int mtu = Integer.getInteger("aeron.mtu.length", 1408);
if (mtu > Configuration.MAX_UDP_PAYLOAD_LENGTH) { mtu = Configuration.MAX_UDP_PAYLOAD_LENGTH; }

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("mtu too large: " + e.getMessage()); System.exit(1); }

When it happens

Trigger: Calling validateMtuLength with mtuLength > 65507, e.g. setting aeron.mtu.length=131072 or an mtu= URI parameter copied from a TCP/tuned value.

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

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= <= HEADER_LENGTH=
• Property = is not a number
• mtuLength= is not a multiple of FRAME_ALIGNMENT=
• mtuLength= > SO_SNDBUF= , increase to match MTU

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

Appendix: source

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

    /**
     * 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
     * sent to the driver to ensure the client has the right to terminate a driver.
     *
     * @return the {@link TerminationValidator}
     */
    public static TerminationValidator terminationValidator()
    {

View on GitHub (pinned to 6d60124e15)