aeron-io/aeron · error · ConfigurationException

mtuLength= > initialWindowLength=

Error message

mtuLength=${mtuLength} > initialWindowLength=${initialWindowLength}

What it means

Configuration.validateInitialWindowLength enforces that a flow-control initial window is at least as large as the MTU, since the receiver window must be able to hold at least one maximum-sized packet. If mtuLength exceeds initialWindowLength the configuration is contradictory and the driver throws ConfigurationException.

Solutions

1. Increase the initial window length to be >= the MTU length
2. Lower the MTU length to be <= the initial window length
3. Check both aeron.mtu.length and aeron.socket.initial.window.length (and channel URI mtu= overrides) so they are consistent

Example fix

// before
ctx.mtuLength(16384).initialWindowLength(8192);
// after
ctx.mtuLength(16384).initialWindowLength(16384);

if (ctx.mtuLength() > ctx.initialWindowLength()) {
    ctx.initialWindowLength(ctx.mtuLength());
}

try { mediaDriver.launch(ctx); } catch (ConfigurationException e) { fixWindowMtuConfig(e); }

When it happens

Trigger: Calling validateInitialWindowLength(initialWindowLength, mtuLength) (directly or via driver/channel setup) with an aeron.mtu.length larger than aeron.socket.initial.window.length, e.g. mtuLength=16384 with initialWindowLength=8192.

Common situations: Raising MTU for jumbo frames without raising the initial window, copy-pasting one value from a sample and forgetting the other, or per-channel URIs overriding MTU above the globally configured window.

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

• mtuLength= <= HEADER_LENGTH=
• 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/d07c523d68b915f7. Report an issue: GitHub.

Appendix: source

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

        }
        catch (final NumberFormatException ex)
        {
            throw new AsciiNumberFormatException(
                "Property " + STREAM_SESSION_LIMIT_PROP_NAME + "=" + streamSessionLimitString + " is not a number");
        }
    }

    /**
     * Validate that the initial window length is greater than MTU.
     *
     * @param initialWindowLength to be validated.
     * @param mtuLength           against which to validate.
     */
    public static void validateInitialWindowLength(final int initialWindowLength, final int mtuLength)
    {
        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);
        }

View on GitHub (pinned to 6d60124e15)