aeron-io/aeron · error · ConfigurationException

AeronArchive.Context.controlRequestChannel must be set

Error message

AeronArchive.Context.controlRequestChannel must be set

What it means

AeronArchive.Context.conclude() validates mandatory configuration before connecting. The controlRequestChannel is the URI of the publication used to send commands to the archive; without it the client cannot be built, so a ConfigurationException is thrown at connect time.

Solutions

Set ctx.controlRequestChannel("aeron:udp?endpoint=<archive-host>:<control-port>") before connect().
Or set the system property io.aeron.archive.client.control.request.channel to the archive's control channel URI.
If using defaults from a properties file, ensure the file is loaded and the property key spelled correctly.
Print/verify with ctx.controlRequestChannel() right before connect to confirm it is non-null.

Example fix

// before
AeronArchive.Context ctx = new AeronArchive.Context();
ctx.controlResponseChannel("aeron:udp?endpoint=localhost:8021");
AeronArchive archive = AeronArchive.connect(ctx);
// after
ctx.controlRequestChannel("aeron:udp?endpoint=localhost:8010")
   .controlResponseChannel("aeron:udp?endpoint=localhost:8021");
AeronArchive archive = AeronArchive.connect(ctx);

Defensive patterns

Strategy: validation

Validate before calling

if (ctx.controlRequestChannel() == null) { ctx.controlRequestChannel("aeron:udp?endpoint=localhost:8010"); }

Prevention

Always set both controlRequestChannel and controlResponseChannel in a shared context factory.
Rely on io.aeron.archive.client.control.request.channel system property with an assert in startup code.
Wrap context creation in a factory method that enforces required fields.
Fail fast in unit tests with a context-completeness check.

When it happens

Trigger: Calling AeronArchive.connect() (or Context.conclude()) with a Context whose controlRequestChannel(String) was never called, typically when constructing the context programmatically instead of via properties/system properties.

Common situations: Forgetting io.aeron.archive.client.control.request.channel system property; copying a Context from another client and forgetting to set the request channel; building a minimal context for tests.

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

Appendix: source

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

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

View on GitHub (pinned to 6d60124e15)