aeron-io/aeron · error · IllegalArgumentException

MTU not in range 32-65504

Error message

MTU not in range 32-65504: ${mtu}

What it means

Thrown by ChannelUriStringBuilder.mtu(Integer) when the MTU is below 32 or above 65504. MTU bounds follow Aeron's frame size constraints (max payload of 65504 = 64KB minus headers, min 32 aligned bytes), and violating them would produce frames the network or driver cannot carry.

Solutions

1. Set MTU within [32, 65504]; typical values are 4096, 8192, 16384, or 65504 for max throughput.
2. Clamp config-provided values: Math.min(65504, Math.max(32, v)).
3. Ensure MTU is a multiple of FRAME_ALIGNMENT (32) to avoid the follow-on alignment error.

Example fix

// before
builder.mtu(65536);
// after
builder.mtu(65504);

if (mtu != null && (mtu < 32 || mtu > 65504)) { throw new IllegalArgumentException("MTU not in range 32-65504: " + mtu); }

boolean isValidMtu(Integer mtu) { return mtu == null || (mtu >= 32 && mtu <= 65504 && (mtu & 31) == 0); }

try { builder.mtu(m); } catch (IllegalArgumentException e) { builder.mtu(4096); }

When it happens

Trigger: builder.mtu(16), builder.mtu(90000), or passing a jumbo value larger than the 64KB frame limit.

Common situations: Confusing IP MTU (1500/9000) with Aeron MTU and setting 65536+; tuning for jumbo frames beyond the frame header limit; accidental 0 or negative config values.

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

• TTL not in range 0-255
• MTU not a multiple of FRAME_ALIGNMENT: mtu=
• >
• failed to fetch remote recording descriptor
• failed to resolve subscription endpoint: channel=" +…

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

Appendix: source

Thrown at aeron-client/src/main/java/io/aeron/ChannelUriStringBuilder.java:610

    {
        return ttl;
    }

    /**
     * Set the maximum transmission unit (MTU) including Aeron header for a datagram payload. If this is greater
     * than the network MTU for UDP then the packet will be fragmented and can amplify the impact of loss.
     *
     * @param mtu the maximum transmission unit including Aeron header for a datagram payload.
     * @return this for a fluent API.
     * @see CommonContext#MTU_LENGTH_PARAM_NAME
     */
    public ChannelUriStringBuilder mtu(final Integer mtu)
    {
        if (null != mtu)
        {
            if (mtu < 32 || mtu > 65504)
            {
                throw new IllegalArgumentException("MTU not in range 32-65504: " + mtu);
            }

            if ((mtu & (FRAME_ALIGNMENT - 1)) != 0)
            {
                throw new IllegalArgumentException("MTU not a multiple of FRAME_ALIGNMENT: mtu=" + mtu);
            }
        }

        this.mtu = mtu;
        return this;
    }

    /**
     * Set the mtu value to be what is in the {@link ChannelUri} which may be null.
     *
     * @param channelUri to read the value from.
     * @return this for a fluent API.
     * @see CommonContext#MTU_LENGTH_PARAM_NAME

View on GitHub (pinned to 6d60124e15)