aeron-io/aeron · error · IllegalArgumentException

>

Error message

${MTU_LENGTH_PARAM_NAME} ${value} > ${Integer.MAX_VALUE}

What it means

Thrown by the builder's mtu(String) parse path when the parsed 'mtu' URI parameter value exceeds Integer.MAX_VALUE. The parameter is parsed as a size (long); anything beyond int range cannot be stored in the builder's Integer mtu field and is rejected before the range checks in mtu(Integer).

Solutions

1. Correct the URI so mtu is within 32-65504, e.g. mtu=16384.
2. Bound-check the long value against Integer.MAX_VALUE (and realistically 65504) before constructing the URI.
3. If sizes come from config with unit suffixes, verify the unit conversion; pass an aligned int to mtu(Integer) directly instead.

Example fix

// before
String mtu = "17179869184";
builder.mtu(mtu);
// after
long v = parseSize("mtu", mtu);
if (v >= 32 && v <= 65504) builder.mtu((int) v);

long v = parseSize("mtu", rawMtu);
if (v > Integer.MAX_VALUE) { throw new IllegalArgumentException("mtu too large"); }
builder.mtu((int) v);

boolean isIntSized(long v) { return v >= 0 && v <= Integer.MAX_VALUE; }

try { builder.mtu(rawMtu); } catch (IllegalArgumentException e) { builder.mtu(16384); }

When it happens

Trigger: A channel URI containing mtu=17179869184 (or any value > 2147483647) passed through builder.mtu(uriParameterValue) — parseSize succeeds as a long but the int cast is refused.

Common situations: Unit-suffixed sizes misparsed (e.g. "16g" intending gibibits landing as huge byte counts); typos adding digits; generating URIs programmatically with a long-typed size that was never bounded.

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' must be a value integer
• MTU not in range 32-65504
• MTU not a multiple of FRAME_ALIGNMENT: mtu=
• invalid entity tag, must be a number
• invalid position

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

Appendix: source

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

     *
     * @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)
        {
            mtu = null;
            return this;
        }
        else
        {
            final long value = parseSize(MTU_LENGTH_PARAM_NAME, mtuValue);
            if (value > Integer.MAX_VALUE)
            {
                throw new IllegalArgumentException(MTU_LENGTH_PARAM_NAME + " " + value + " > " + Integer.MAX_VALUE);
            }

            return mtu((int)value);
        }
    }

    /**
     * Get 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.
     *
     * @return the maximum transmission unit (MTU) including Aeron header for a datagram payload.
     * @see CommonContext#MTU_LENGTH_PARAM_NAME
     */
    public Integer mtu()
    {
        return mtu;
    }

View on GitHub (pinned to 6d60124e15)