aeron-io/aeron · error · ConfigurationException

egressListener must be specified on AeronCluster.Context

Error message

egressListener must be specified on AeronCluster.Context

What it means

Context.conclude() installs a placeholder egressListener that throws ConfigurationException('egressListener must be specified on AeronCluster.Context') when no real listener was provided. Egress events would otherwise be silently dropped, so the library fails instead of losing messages.

Solutions

Set ctx.egressListener((clusterSessionId, timestamp, buffer, offset, length, header) -> ...) before connect()
Or set a controlledEgressListener so conclude() does not install the throwing default for the plain listener path
If you intentionally ignore responses, supply a no-op listener rather than leaving it null

Example fix

// before
new AeronCluster.Context().ingressChannel(...).egressChannel(...); // no listener
// after
new AeronCluster.Context()
    .ingressChannel(...)
    .egressChannel(...)
    .egressListener((clusterSessionId, timestamp, buffer, offset, length, header) ->
        handleEgress(buffer, offset, length));

Defensive patterns

Strategy: validation

Validate before calling

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

Prevention

Always register at least one egress listener in your client bootstrap
Use a no-op listener when responses are intentionally ignored rather than leaving null

When it happens

Trigger: Connecting an AeronCluster without calling ctx.egressListener(...) and without providing a controlledEgressListener default, then receiving an egress event that invokes the placeholder.

Common situations: Client code expecting only pollEgress via the controlled listener; forgetting the plain listener when both subscription modes are relevant; copy-paste of a Context from a project that sets listeners elsewhere.

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

Appendix: source

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

                ownsAeronClient = true;
            }

            if (null == idleStrategy)
            {
                idleStrategy = new BackoffIdleStrategy(1, 10, 1000, 1000);
            }

            if (null == credentialsSupplier)
            {
                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.
         *

View on GitHub (pinned to 6d60124e15)