aeron-io/aeron · error · ConfigurationException

egressChannel must be specified

Error message

egressChannel must be specified

What it means

AeronCluster requires an egress channel so the cluster can send responses back to the client. Context.conclude() throws ConfigurationException when egressChannel is null or empty; the channel must be a valid URI (typically aeron:udp?endpoint=<client>:<port>).

Solutions

1. Set ctx.egressChannel("aeron:udp?endpoint=<host>:<port>") before connect()
2. For a wildcard local port use e.g. aeron:udp?endpoint=localhost:0
3. Verify your config loader actually populates egressChannel (log it before connect)

Example fix

// before
new AeronCluster.Context().ingressChannel("aeron:udp?endpoint=localhost:20000");
// after
new AeronCluster.Context()
    .ingressChannel("aeron:udp?endpoint=localhost:20000")
    .egressChannel("aeron:udp?endpoint=localhost:0");

if (ctx.egressChannel() == null || ctx.egressChannel().isEmpty()) {
    throw new IllegalArgumentException("egressChannel must be set before AeronCluster.connect()");
}

When it happens

Trigger: Calling AeronCluster.connect() or ctx.conclude() without calling ctx.egressChannel(...), or setting it to an empty string.

Common situations: Copying only the ingress half of a sample config; refactoring Context setup and dropping the egress line; env-driven config where the egress property is absent.

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

• ingressChannel must be specified
• AeronArchive.Context.messageRetryAttempts must be > 0, got:
• AeronCluster.Context.clientName length must be <=…
• AeronCluster.Context ingressEndpoints must be null when…
• applicationSpecificFeedback length must be equal to

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

Appendix: source

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

            }

            if (Strings.isEmpty(ingressChannel))
            {
                throw new ConfigurationException("ingressChannel must be specified");
            }

            if (ingressChannel.startsWith(CommonContext.IPC_CHANNEL))
            {
                if (null != ingressEndpoints)
                {
                    throw new ConfigurationException(
                        "AeronCluster.Context ingressEndpoints must be null when using IPC ingress");
                }
            }

            if (Strings.isEmpty(egressChannel))
            {
                throw new ConfigurationException("egressChannel must be specified");
            }

            final ChannelUri egressChannelUri = ChannelUri.parse(egressChannel);
            if (egressChannelUri.isUdp())
            {
                egressChannelUri.put(REJOIN_PARAM_NAME, "false");
                egressChannel = egressChannelUri.toString();
            }

            if (clientName.length() > Aeron.Configuration.MAX_CLIENT_NAME_LENGTH)
            {
                throw new ConfigurationException(
                    "AeronCluster.Context.clientName length must be <= " + Aeron.Configuration.MAX_CLIENT_NAME_LENGTH);
            }

            if (null == aeron)
            {
                aeron = Aeron.connect(

View on GitHub (pinned to 6d60124e15)