aeron-io/aeron · error · ConfigurationException

initialWindowLength=

Error message

initialWindowLength=${initialWindowLength} > SO_RCVBUF=${soRcvBuf}, increase ${SOCKET_RCVBUF_LENGTH_PROP_NAME} limits to match initialWindowLength

What it means

Aeron validates that the flow-control initial window length does not exceed the OS socket receive buffer (SO_RCVBUF); otherwise the receiver cannot buffer a full window of data and throughput would be silently capped or datagrams dropped. Configuration throws this ConfigurationException when ctx.initialWindowLength() > soRcvBuf during driver conclusion.

Solutions

Increase aeron.socket.rcvbuf.length (SOCKET_RCVBUF_LENGTH_PROP_NAME) to >= initialWindowLength
Or lower aeron.initial.window.length to fit within SO_RCVBUF
Raise OS-level net.core.rmem_default / rmem_max if relying on OS defaults
Also ensure the application reads fast enough; a window larger than buffers only masks backpressure

Example fix

// before
ctx.initialWindowLength(8 * 1024 * 1024);
ctx.socketRcvbufLength(1024 * 1024);
// after
ctx.initialWindowLength(8 * 1024 * 1024);
ctx.socketRcvbufLength(8 * 1024 * 1024); // >= initialWindowLength

Defensive patterns

Strategy: validation

Validate before calling

int soRcvBuf = socketRcvbufLength != 0 ? socketRcvbufLength : osDefaultSocketRcvbufLength;
if (initialWindowLength > soRcvBuf) {
    throw new IllegalStateException("raise aeron.socket.rcvbuf.length to >= " + initialWindowLength);
}

Try / catch

try {
    mediaCtx.conclude();
} catch (ConfigurationException e) {
    if (e.getMessage().contains("SO_RCVBUF")) {
        mediaCtx.socketRcvbufLength(mediaCtx.initialWindowLength());
        mediaCtx.conclude();
    } else { throw e; }
}

Prevention

Keep initialWindowLength <= SO_RCVBUF in config templates
Raise net.core.rmem_max when using multi-MB windows
Document the window/socket-buffer dependency in your deployment runbook

When it happens

Trigger: Running Configuration.validateSocketBufferLengths(ctx) when aeron.socket.rcvbuf.length (or the OS default when 0) is smaller than aeron.initial.window.length.

Common situations: Increasing initial window for high-throughput links while leaving SO_RCVBUF at defaults or explicitly low; containerized environments with small rmem limits; copying window tuning from guides without matching socket buffer settings.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

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

Appendix: source

Thrown at aeron-driver/src/main/java/io/aeron/driver/Configuration.java:2531

                " attempted=" + ctx.socketRcvbufLength() + ", actual=" + ctx.osMaxSocketRcvbufLength());
        }

        final int soSndBuf = 0 == ctx.socketSndbufLength() ?
            ctx.osDefaultSocketSndbufLength() : ctx.socketSndbufLength();

        if (ctx.mtuLength() > soSndBuf)
        {
            throw new ConfigurationException(
                "mtuLength=" + ctx.mtuLength() + " > SO_SNDBUF=" + soSndBuf +
                ", increase " + SOCKET_SNDBUF_LENGTH_PROP_NAME + " to match MTU");
        }

        final int soRcvBuf = 0 == ctx.socketRcvbufLength() ?
            ctx.osDefaultSocketRcvbufLength() : ctx.socketRcvbufLength();

        if (ctx.initialWindowLength() > soRcvBuf)
        {
            throw new ConfigurationException(
                "initialWindowLength=" + ctx.initialWindowLength() + " > SO_RCVBUF=" + soRcvBuf +
                ", increase " + SOCKET_RCVBUF_LENGTH_PROP_NAME + " limits to match initialWindowLength");
        }
    }

    /**
     * Validate that page size is valid and alignment is valid.
     *
     * @param pageSize to be checked.
     * @throws ConfigurationException if the size is not as expected.
     */
    public static void validatePageSize(final int pageSize)
    {
        validateValueRange(pageSize, PAGE_MIN_SIZE, PAGE_MAX_SIZE, "filePageSize");

        if (!BitUtil.isPowerOfTwo(pageSize))
        {
            throw new ConfigurationException("filePageSize not a power of 2: " + pageSize);

View on GitHub (pinned to 6d60124e15)