What causes "value exceeds maximum permitted: value=${value}" in aeron-io/aeron?

Reduce the socket_sndbuf value in the URI to at most Integer.MAX_VALUE (2147483647) bytes.

aeron-io/aeron · error · IllegalArgumentException

value exceeds maximum permitted: value=

Error message

value exceeds maximum permitted: value=${value}

What it means

Thrown when parsing the socket_sndbuf parameter from a channel URI string. The parsed size is stored internally as an int, so any value greater than Integer.MAX_VALUE is rejected with this error. The parameter must fit in a positive 32-bit int (bytes).

Solutions

Reduce the socket_sndbuf value in the URI to at most Integer.MAX_VALUE (2147483647) bytes.
Remember the value is bytes, not bits: divide bit-based sizes by 8 before specifying.
If you need buffers larger than 2GB, set them at the OS/socket level instead of via the channel URI.

Example fix

// before
String uri = "aeron:udp?endpoint=localhost:40456|socket_sndbuf=4294967296"; // 4GB > Integer.MAX_VALUE
// after
String uri = "aeron:udp?endpoint=localhost:40456|socket_sndbuf=2147483647";

Defensive patterns

Strategy: validation

Validate before calling

long value = parseSize(uriParam);
if (value > Integer.MAX_VALUE) {
    throw new IllegalArgumentException("socket_sndbuf must be <= " + Integer.MAX_VALUE + ", got " + value);
}

Type guard

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

Try / catch

try {
    builder.socketSndbufLength((int) value);
} catch (IllegalArgumentException e) {
    log.warn("socket_sndbuf too large, clamping", e);
    builder.socketSndbufLength(Integer.MAX_VALUE);
}

Prevention

Clamp configured buffer sizes to Integer.MAX_VALUE before building the URI.
Remember values are bytes; convert bit-based OS settings accordingly.
For >2GB buffers, tune at the OS level instead of the channel URI.

When it happens

Trigger: Building a ChannelUriStringBuilder via ChannelUri.parse(...).toBuilder() or setSocketSndbufLength parsing from a URI containing socket_sndbuf=<value greater than 2147483647>.

Common situations: Configuring very large socket send buffers copied from OS-level settings (e.g. net.core.wmem_max values expressed beyond 2GB); typos adding an extra digit; unit confusion (bits vs bytes).

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

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

Appendix: source

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

     *
     * @param channelUri to read the value from.
     * @return this for a fluent API.
     * @see CommonContext#SOCKET_SNDBUF_PARAM_NAME
     */
    public ChannelUriStringBuilder socketSndbufLength(final ChannelUri channelUri)
    {
        final String valueStr = channelUri.get(SOCKET_SNDBUF_PARAM_NAME);
        if (null == valueStr)
        {
            this.socketSndbufLength = null;
            return this;
        }
        else
        {
            final long value = parseSize(SOCKET_SNDBUF_PARAM_NAME, valueStr);
            if (value > Integer.MAX_VALUE)
            {
                throw new IllegalArgumentException("value exceeds maximum permitted: value=" + value);
            }

            return socketSndbufLength((int)value);
        }
    }

    /**
     * Get the underlying OS send buffer length setting.
     *
     * @return underlying OS send buffer length setting or null if not specified.
     * @see CommonContext#SOCKET_SNDBUF_PARAM_NAME
     */
    public Integer socketSndbufLength()
    {
        return socketSndbufLength;
    }

    /**

View on GitHub (pinned to 6d60124e15)