aeron-io/aeron · error · ConfigurationException

AeronArchive.Context.controlResponseChannel must be set

Error message

AeronArchive.Context.controlResponseChannel must be set

What it means

AeronArchive.Context.conclude() requires the controlResponseChannel — the subscription URI on which the client receives archive replies. When it is null after conclusion-time validation, ConfigurationException with this message is thrown before any connection is attempted.

Solutions

Set ctx.controlResponseChannel("aeron:udp?endpoint=<client-host>:<response-port>") before connect().
Or set the system property io.aeron.archive.client.control.response.channel.
Ensure the response channel endpoint/port are routable from the client to the archive's control response stream.
Log the context values in a startup check to catch missing configuration early.

Example fix

// before
ctx.controlRequestChannel("aeron:udp?endpoint=localhost:8010");
// after
ctx.controlRequestChannel("aeron:udp?endpoint=localhost:8010")
   .controlResponseChannel("aeron:udp?endpoint=localhost:8020");

Defensive patterns

Strategy: validation

Validate before calling

if (ctx.controlResponseChannel() == null) { throw new IllegalArgumentException("controlResponseChannel required"); }

Prevention

Set the response channel before calling connect(); treat it as mandatory config.
Load AeronArchive.Configuration defaults and verify them at startup.
Use distinct response endpoint ports per client to avoid collisions.
Keep context setup in one reviewed code path, not scattered setters.

When it happens

Trigger: connect() with a Context that has controlRequestChannel set but controlResponseChannel(String) never called, or a null value passed explicitly.

Common situations: Setting only the request channel by mistake; migration from older code/config that used a different property name; environment property missing so the setter was never invoked.

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

Appendix: source

Thrown at aeron-archive/src/main/java/io/aeron/archive/client/AeronArchive.java:3100

        /**
         * 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 (null == controlRequestChannel)
            {
                throw new ConfigurationException("AeronArchive.Context.controlRequestChannel must be set");
            }

            if (null == controlResponseChannel)
            {
                throw new ConfigurationException("AeronArchive.Context.controlResponseChannel must be set");
            }

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

            if (messageRetryAttempts <= 0)
            {
                throw new ConfigurationException("AeronArchive.Context.messageRetryAttempts must be > 0, got: " +
                    messageRetryAttempts);
            }

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

View on GitHub (pinned to 6d60124e15)