aeron-io/aeron · error · ConfigurationException

AeronCluster.Context ingressEndpoints must be null when…

Error message

AeronCluster.Context ingressEndpoints must be null when using IPC ingress

What it means

When ingressChannel is the IPC channel (aeron:ipc), ingress must go over shared memory to the co-located cluster node, so per-member ingressEndpoints cannot be used. Context.conclude() throws ConfigurationException if both IPC ingress and a non-null ingressEndpoints map are set, since they are mutually exclusive.

Solutions

1. Remove the ctx.ingressEndpoints(...) call when using aeron:ipc
2. Or change ingressChannel to a UDP channel (aeron:udp?...) if you actually need remote member endpoints

Example fix

// before
ctx.ingressChannel("aeron:ipc").ingressEndpoints("0=localhost:20001,1=localhost:20002");
// after
ctx.ingressChannel("aeron:ipc"); // ingressEndpoints must be null for IPC

if (ctx.ingressChannel() != null && ctx.ingressChannel().startsWith("aeron:ipc")
    && ctx.ingressEndpoints() != null) {
    throw new IllegalArgumentException("ingressEndpoints must be null when ingressChannel is aeron:ipc");
}

When it happens

Trigger: Setting ctx.ingressChannel("aeron:ipc") while ctx.ingressEndpoints(...) is non-null, then calling AeronCluster.connect()/conclude().

Common situations: Switching a remote-client config to IPC for local testing without clearing previously-set ingressEndpoints; merge of two configs that each set one of the two options.

Related errors

• invalid fileIoMaxLength=
• segment file length not a power of 2
• segment file length not in valid range
• AeronArchive.Context.messageRetryAttempts must be > 0, got:
• recordingId must be set

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

Appendix: source

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

         * 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())
            {
                egressChannelUri.put(REJOIN_PARAM_NAME, "false");
                egressChannel = egressChannelUri.toString();
            }

            if (clientName.length() > Aeron.Configuration.MAX_CLIENT_NAME_LENGTH)
            {

View on GitHub (pinned to 6d60124e15)