aeron-io/aeron · error · ConfigurationException

ingressChannel must be specified

Error message

ingressChannel must be specified

What it means

AeronCluster.connect() requires an ingress channel via AeronCluster.Context.ingressChannel. The ingress channel is the transport (e.g. aeron:udp?endpoint=...) used to send client requests to the cluster; without it the client cannot communicate with cluster members, so conclude() fails fast with a ConfigurationException.

Solutions

1. Set ctx.ingressChannel("aeron:udp?endpoint=...") matching the cluster's ingress endpoints before connect()
2. If using IPC within the same host, set ingressChannel to CommonContext.IPC_CHANNEL ("aeron:ipc") and leave ingressEndpoints null
3. If you rely on the cluster-ingress-endpoints property/channel URI, pass it in via Context.ingressChannel instead of assuming a default

Example fix

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

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

When it happens

Trigger: Calling AeronCluster.connect() or ctx.conclude() with an ingressChannel that is null or the empty string (Strings.isEmpty).

Common situations: Building a Context programmatically and forgetting ingressChannel; copying sample configs that only set egressChannel; loading config from properties where the ingress key is missing.

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

• egressChannel 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/57956e4b2484df84. Report an issue: GitHub.

Appendix: source

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

            catch (final CloneNotSupportedException ex)
            {
                throw new RuntimeException(ex);
            }
        }

        /**
         * Conclude configuration by setting up defaults when specifics are not provided.
         */
        public void conclude()
        {
            if ((boolean)IS_CONCLUDED_VH.getAndSet(this, true))
            {
                throw new ConcurrentConcludeException();
            }

            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())

View on GitHub (pinned to 6d60124e15)