aeron-io/aeron · error · IllegalStateException

Initial window greater than SO_RCVBUF for channel: rcv-wnd=

Error message

Initial window greater than SO_RCVBUF for channel: rcv-wnd=<receiverWindowLength> so-rcvbuf=<osDefaultSocketRcvbufLength> (OS default) existingChannel=<existingChannel> channel=<channel>

What it means

When the channel URI does not set so-rcvbuf (value 0, meaning OS default), the receiver window must still not exceed the OS default socket receive buffer (ctx.osDefaultSocketRcvbufLength()). The driver throws IllegalStateException naming the OS default so the user knows which limit was exceeded.

Solutions

1. Set so-rcvbuf in the channel URI to at least the desired receiver window.
2. Lower receiver-window-length to fit under the OS default buffer.
3. Raise OS limits: net.core.rmem_max and net.core.rmem_default via sysctl, then restart.
4. Set MediaDriver.Context osDefaultSocketRcvbufLength probing appropriately by ensuring the OS buffers are large before driver start.

Example fix

// before
"aeron:udp?endpoint=localhost:40456|rcv-wnd=8388608" // relies on OS default
// after
"aeron:udp?endpoint=localhost:40456|rcv-wnd=8388608|so-rcvbuf=8388608" // or raise net.core.rmem_max

if (soRcvbuf == 0 && rcvWnd > osDefaultRcvbuf) {
    throw new IllegalArgumentException("rcv-wnd (" + rcvWnd + ") exceeds OS default SO_RCVBUF (" + osDefaultRcvbuf + "); set so-rcvbuf or raise rmem_max");
}

When it happens

Trigger: Adding a subscription with a large receiver-window-length (or a driver-side default initial-window-endpoint exceeding OS defaults) on a channel URI without so-rcvbuf, when rcv-wnd > osDefaultSocketRcvbufLength.

Common situations: High-throughput deployments raising initial window without configuring so-rcvbuf; containers/hosts with small net.core.rmem_max making the OS default tiny; migrating configs to machines with different OS defaults.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Initial window greater than SO_RCVBUF for channel: rcv-wnd=
• could not re-resolve: control=
• could not re-resolve: endpoint=
• could not resolve control address:
• could not resolve endpoint address:

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

Appendix: source

Thrown at aeron-driver/src/main/java/io/aeron/driver/SubscriptionParams.java:184

    }

    static void validateInitialWindowForRcvBuf(
        final SubscriptionParams params,
        final String channel,
        final int channelSocketRcvbufLength,
        final MediaDriver.Context ctx,
        final String existingChannel)
    {
        if (0 != channelSocketRcvbufLength && params.receiverWindowLength > channelSocketRcvbufLength)
        {
            throw new IllegalStateException(
                "Initial window greater than SO_RCVBUF for channel: rcv-wnd=" + params.receiverWindowLength +
                " so-rcvbuf=" + channelSocketRcvbufLength +
                (null == existingChannel ? "" : (" existingChannel=" + existingChannel)) + " channel=" + channel);
        }
        else if (0 == channelSocketRcvbufLength && params.receiverWindowLength > ctx.osDefaultSocketRcvbufLength())
        {
            throw new IllegalStateException(
                "Initial window greater than SO_RCVBUF for channel: rcv-wnd=" + params.receiverWindowLength +
                " so-rcvbuf=" + ctx.osDefaultSocketRcvbufLength() + " (OS default)" +
                (null == existingChannel ? "" : (" existingChannel=" + existingChannel)) + " channel=" + channel);
        }
    }

    public String toString()
    {
        return "SubscriptionParams" +
            "\n{" +
            "\n    initialTermId=" + initialTermId +
            "\n    termId=" + termId +
            "\n    termOffset=" + termOffset +
            "\n    sessionId=" + sessionId +
            "\n    hasJoinPosition=" + hasJoinPosition +
            "\n    hasSessionId=" + hasSessionId +
            "\n    isReliable=" + isReliable +
            "\n    isRejoin=" + isRejoin +

View on GitHub (pinned to 6d60124e15)