aeron-io/aeron · error · IllegalArgumentException

MTU not a multiple of FRAME_ALIGNMENT: mtu=

Error message

MTU not a multiple of FRAME_ALIGNMENT: mtu=${mtu}

What it means

Thrown by ChannelUriStringBuilder.mtu(Integer) when the MTU is not a multiple of FRAME_ALIGNMENT (32 bytes). Aeron messages are written in 32-byte-aligned frames, so an unaligned MTU would break framing on the term buffer.

Solutions

1. Round the MTU down/up to a multiple of 32, e.g. (mtu / FRAME_ALIGNMENT) * FRAME_ALIGNMENT.
2. Use standard aligned values like 4096, 8192, 16384, or 65504.
3. For a 1500-byte network path use 1408 (44 * 32) or similar aligned value below the IP MTU.

Example fix

// before
builder.mtu(1500);
// after
builder.mtu(1408); // multiple of FRAME_ALIGNMENT (32)

if (mtu != null && (mtu & (FrameDescriptor.FRAME_ALIGNMENT - 1)) != 0) { throw new IllegalArgumentException("MTU must be a multiple of 32"); }

boolean isAlignedMtu(Integer mtu) { return mtu == null || (mtu & 31) == 0; }

try { builder.mtu(m); } catch (IllegalArgumentException e) { builder.mtu((m / 32) * 32); }

When it happens

Trigger: builder.mtu(1500) or builder.mtu(9000) — both not divisible by 32 — while within the 32-65504 range.

Common situations: Copying the NIC's IP MTU (1500) or jumbo frame size (9000) directly into Aeron's MTU without aligning; tuning guides that quote network MTU rather than Aeron MTU.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• invalid position
• MTU not in range 32-65504
• >
• invalid position= does not have frame alignment=
• mtuLength= is not a multiple of FRAME_ALIGNMENT=

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

Appendix: source

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

     * 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
     */
    public ChannelUriStringBuilder mtu(final ChannelUri channelUri)
    {
        final String mtuValue = channelUri.get(MTU_LENGTH_PARAM_NAME);
        if (null == mtuValue)

View on GitHub (pinned to 6d60124e15)