aeron-io/aeron · error · IllegalArgumentException

Invalid length

Error message

Invalid ${paramName} length: ${size}

What it means

Thrown when a socket-buffer or receiver-window parameter (socket-rcvbuf-length, socket-sndbuf-length, receiver-window-length) parses to a value below 0 or above Integer.MAX_VALUE. Aeron clamps accepted buffer sizes to the positive int range.

Solutions

1. Use a size between 0 and 2147483647, e.g. socket-rcvbuf-length=2m
2. Lower the requested buffer size; OS SO_RCVBUF limits are usually far below 2GB anyway
3. Tune the OS-level net.core.rmem_max/wmem_max instead of inflating the URI value beyond int range

Example fix

// before
"aeron:udp?endpoint=...|socket-rcvbuf-length=4g"
// after
"aeron:udp?endpoint=...|socket-rcvbuf-length=2m"

long size = SystemUtil.parseSize("socket-rcvbuf-length", value);
if (size < 0 || size > Integer.MAX_VALUE) throw new IllegalArgumentException("size out of range: " + size);

static boolean isValidBufferLength(String v) { try { long s = SystemUtil.parseSize("p", v); return s >= 0 && s <= Integer.MAX_VALUE; } catch (Exception e) { return false; } }

try { pub = aeron.addPublication(uri, stream); } catch (IllegalArgumentException e) { log.error("buffer length invalid: {}", e.getMessage()); }

When it happens

Trigger: Setting e.g. socket-rcvbuf-length=4g (4294967296, > Integer.MAX_VALUE) or a negative size in the channel URI.

Common situations: OS tuning values copied from guides that exceed the 2GB int limit, unit confusion (g vs m suffix from SystemUtil.parseSize).

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

• Aeron URIs must start with 'aeron:', found
• channelReceiveTimestampOffset must be a number or the value
• channelSendTimestampOffset must be a number or the value
• destinations must not contain the key
• difference greater than 2^31 - 1: termId=

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

Appendix: source

Thrown at aeron-driver/src/main/java/io/aeron/driver/media/UdpChannel.java:364

     * Parse a buffer length for a given URI paramName with a format specified by
     * {@link SystemUtil#parseSize(String, String)}, clamping the range to 0 <= x <= Integer.MAX_VALUE.
     *
     * @param channelUri to get the value from.
     * @param paramName  key for the parameter.
     * @return value as an integer.
     * @see SystemUtil#parseSize(String, String)
     */
    public static int parseBufferLength(final ChannelUri channelUri, final String paramName)
    {
        int socketBufferLength = 0;

        final String paramValue = channelUri.get(paramName);
        if (null != paramValue)
        {
            final long size = SystemUtil.parseSize(paramName, paramValue);
            if (size < 0 || size > Integer.MAX_VALUE)
            {
                throw new IllegalArgumentException("Invalid " + paramName + " length: " + size);
            }
            socketBufferLength = (int)size;
        }

        return socketBufferLength;
    }

    /**
     * Parse the control mode from the channel URI. If the value is null or unknown then {@link ControlMode#NONE} will
     * be used.
     *
     * @param channelUri to parse the control mode from.
     * @return an enum value representing the control mode.
     */
    public static ControlMode parseControlMode(final ChannelUri channelUri)
    {
        final String paramValue = channelUri.get(MDC_CONTROL_MODE_PARAM_NAME);
        if (null == paramValue)

View on GitHub (pinned to 6d60124e15)