aeron-io/aeron · error · ConfigurationException

mtuLength= > SO_SNDBUF= , increase to match MTU

Error message

mtuLength=${mtuLength} > SO_SNDBUF=${soSndBuf}, increase ${SOCKET_SNDBUF_LENGTH_PROP_NAME} to match MTU

What it means

During driver conclusion, Aeron validates that the configured MTU length is not larger than the OS socket send buffer (SO_SNDBUF), because a datagram larger than the send buffer cannot be sent. If ctx.mtuLength() exceeds the effective SO_SNDBUF (explicitly configured or OS default), Configuration throws this ConfigurationException and the driver fails to start.

Solutions

Increase aeron.socket.sndbuf.length (SOCKET_SNDBUF_LENGTH_PROP_NAME) to be >= mtuLength
Or lower aeron.mtu.length so it fits within the current SO_SNDBUF
If relying on OS defaults, raise the OS-level net.core.wmem_default / wmem_max so the default SO_SNDBUF exceeds the MTU

Example fix

// before
ctx.mtuLength(16384);
ctx.socketSndbufLength(8192);
// after
ctx.mtuLength(16384);
ctx.socketSndbufLength(65536); // >= mtuLength

Defensive patterns

Strategy: validation

Validate before calling

int soSndBuf = socketSndbufLength != 0 ? socketSndbufLength : osDefaultSocketSndbufLength;
if (mtuLength > soSndBuf) {
    throw new IllegalStateException("raise aeron.socket.sndbuf.length to >= " + mtuLength);
}

Try / catch

try {
    mediaCtx.conclude();
} catch (ConfigurationException e) {
    if (e.getMessage().contains("SO_SNDBUF")) {
        mediaCtx.socketSndbufLength(mediaCtx.mtuLength());
        mediaCtx.conclude();
    } else { throw e; }
}

Prevention

Set SO_SNDBUF and MTU together as a pair in your config tooling
Check OS limits (net.core.wmem_max) before deploying large-MTU configs
Validate driver context in CI before shipping configuration

When it happens

Trigger: Running Configuration.validateSocketBufferLengths(ctx) when ctx.mtuLength() > soSndBuf, i.e. aeron.socket.sndbuf.length (or the OS default when 0) is smaller than aeron.mtu.length.

Common situations: Raising MTU (e.g. to 16384) while the OS socket send buffer stays at the default (~212992 bytes is fine, but container/limited environments or explicitly low Aeron SO_SNDBUF settings are not); tuning down SO_SNDBUF for memory savings while keeping a large MTU.

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/285dda78ab0d6671. Report an issue: GitHub.

Appendix: source

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

        {
            System.err.println(
                "WARNING: Could not set desired SO_SNDBUF, adjust OS to allow " + SOCKET_SNDBUF_LENGTH_PROP_NAME +
                " attempted=" + ctx.socketSndbufLength() + ", actual=" + ctx.osMaxSocketSndbufLength());
        }

        if (ctx.osMaxSocketRcvbufLength() < ctx.socketRcvbufLength())
        {
            System.err.println(
                "WARNING: Could not set desired SO_RCVBUF, adjust OS to allow " + SOCKET_RCVBUF_LENGTH_PROP_NAME +
                " 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.
     *

View on GitHub (pinned to 6d60124e15)