aeron-io/aeron · error · ConfigurationException

controlledEgressListener must be specified on…

Error message

controlledEgressListener must be specified on AeronCluster.Context

What it means

Context.conclude() installs a placeholder controlledEgressListener that throws ConfigurationException when none was supplied. The controlled listener offers backpressured, poll-style handling of cluster responses; without a real implementation the library refuses to silently drop egress events.

Solutions

Set ctx.controlledEgressListener((clusterSessionId, timestamp, buffer, offset, length, header) -> ...) before connect()
Or set a plain egressListener if you prefer fire-and-forget semantics and that is the installed default
Provide a no-op ControlledEgressListener if responses are intentionally ignored

Example fix

// before
ctx.egressListener((s, t, b, o, l, h) -> handle(b, o, l)); // controlled listener missing
// after
ctx.egressListener((s, t, b, o, l, h) -> handle(b, o, l))
   .controlledEgressListener((s, t, b, o, l, h) -> { handle(b, o, l); return l; });

Defensive patterns

Strategy: validation

Validate before calling

if (ctx.controlledEgressListener() == null && ctx.egressListener() == null) {
    throw new IllegalArgumentException("provide controlledEgressListener or egressListener before connect()");
}

Prevention

Register both listener styles explicitly in shared bootstrap code
Document in your client wrapper that listeners are mandatory

When it happens

Trigger: Connecting an AeronCluster without calling ctx.controlledEgressListener(...) (and without a plain egressListener covering the path), then polling egress so the placeholder is invoked.

Common situations: Applications that register only the simple egressListener but poll via the controlled path (or vice versa); generated/config-driven Context setup missing the callback.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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

Appendix: source

Thrown at aeron-cluster/src/main/java/io/aeron/cluster/client/AeronCluster.java:1547

                credentialsSupplier = new NullCredentialsSupplier();
            }

            if (null == egressListener)
            {
                egressListener =
                    (clusterSessionId, timestamp, buffer, offset, length, header) ->
                    {
                        throw new ConfigurationException(
                            "egressListener must be specified on AeronCluster.Context");
                    };
            }

            if (null == controlledEgressListener)
            {
                controlledEgressListener =
                    (clusterSessionId, timestamp, buffer, offset, length, header) ->
                    {
                        throw new ConfigurationException(
                            "controlledEgressListener must be specified on AeronCluster.Context");
                    };
            }
        }

        /**
         * Has the context had the {@link #conclude()} method called.
         *
         * @return true if the {@link #conclude()} method has been called.
         */
        public boolean isConcluded()
        {
            return isConcluded;
        }

        /**
         * Set the message timeout in nanoseconds to wait for sending or receiving a message.
         *

View on GitHub (pinned to 6d60124e15)