What causes "probe socket: {ex}" in aeron-io/aeron?

Check and raise the file descriptor limit (ulimit -n) and verify the process is not leaking sockets.

aeron-io/aeron · error · AeronException

probe socket

Error message

probe socket: {ex}

What it means

Thrown during MediaDriver.Context initialization while probing the OS socket limits: the driver opens a probe socket, tries to set SO_RCVBUF to Integer.MAX_VALUE and read back the OS maximum; if any IOException occurs during this probing it wraps it in AeronException. It indicates the process cannot create/configure sockets at all (e.g. resource exhaustion or restricted environment).

Solutions

Check and raise the file descriptor limit (ulimit -n) and verify the process is not leaking sockets.
Verify the runtime allows socket creation (container seccomp/AppArmor profiles, security options) and that a network stack exists.
Test with a trivial Java socket program in the same environment to isolate the cause.
Catch AeronException at driver launch and log the cause; run the driver in an unrestricted host/network namespace.

Example fix

// before
MediaDriver.launch(); // fails in restricted container
// after
// in Docker: run with adequate network privileges
docker run --network=host --ulimit nofile=65536:65536 mydriver-image
// then
MediaDriver.launch();

Defensive patterns

Strategy: try-catch

Validate before calling

try (DatagramSocket probe = new DatagramSocket()) {
    probe.setOption(StandardSocketOptions.SO_RCVBUF, Integer.MAX_VALUE); // fails here in restricted envs
}

Try / catch

try {
    mediaDriver = MediaDriver.launch();
} catch (AeronException e) {
    if (e.getMessage().startsWith("probe socket:")) {
        throw new IllegalStateException("environment cannot create/configure sockets; check fd limits and container security profile", e);
    } else { throw e; }
}

Prevention

Verify socket creation works in the target container/host before deploying
Raise ulimit -n for the driver process
Keep container seccomp profiles permissive for network syscalls
Monitor fd usage to prevent exhaustion

When it happens

Trigger: Context.concludeBytesOsDefaults probing when socket creation fails due to file-descriptor exhaustion, no network permission (restricted container/seccomp), or the OS rejecting socket option operations with an IOException.

Common situations: Running in a sandboxed container without CAP_NET_RAW/network syscalls allowed; ulimit -n (fd limit) already hit; IPv4/IPv6 stack disabled so the probe socket cannot be opened; overly strict security profiles blocking setsockopt.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

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

Appendix: source

Thrown at aeron-driver/src/main/java/io/aeron/driver/MediaDriver.java:4320

            {
                return;
            }

            try (DatagramChannel probe = DatagramChannel.open())
            {
                osDefaultSocketSndbufLength = probe.getOption(StandardSocketOptions.SO_SNDBUF);

                probe.setOption(StandardSocketOptions.SO_SNDBUF, Integer.MAX_VALUE);
                osMaxSocketSndbufLength = probe.getOption(StandardSocketOptions.SO_SNDBUF);

                osDefaultSocketRcvbufLength = probe.getOption(StandardSocketOptions.SO_RCVBUF);

                probe.setOption(StandardSocketOptions.SO_RCVBUF, Integer.MAX_VALUE);
                osMaxSocketRcvbufLength = probe.getOption(StandardSocketOptions.SO_RCVBUF);
            }
            catch (final IOException ex)
            {
                throw new AeronException("probe socket: " + ex, ex);
            }
        }

        @SuppressWarnings({ "MethodLength", "deprecation" })
        void concludeNullProperties()
        {
            if (null == tempBuffer)
            {
                tempBuffer = new UnsafeBuffer(new byte[METADATA_LENGTH]);
            }

            if (null == epochClock)
            {
                epochClock = SystemEpochClock.INSTANCE;
            }

            if (null == nanoClock)
            {

View on GitHub (pinned to 6d60124e15)