aeron-io/aeron · error · ConfigurationException

Archive.Context.archiveClientContext.controlResponseChannel…

Error message

Archive.Context.archiveClientContext.controlResponseChannel must be set if Archive.Context.controlChannelEnabled is false

What it means

When the archive control channel is disabled (controlChannelEnabled=false), Archive still needs a control-response channel for its internal archive client, which it can no longer derive. If Archive.Context.archiveClientContext.controlResponseChannel is not set in that case, Archive throws ConfigurationException.

Solutions

1. Set archiveClientContext.controlResponseChannel("aeron:udp?endpoint=<host>:0") (or an appropriate local channel) when disabling the control channel.
2. If a control channel is actually required, leave controlChannelEnabled(true) and configure it.
3. Review Archive.Configuration defaults for the control response channel and set it explicitly in embedded deployments.

Example fix

// before
ctx.controlChannelEnabled(false);
// after
ctx.controlChannelEnabled(false)
   .archiveClientContext(new Aeron.Context()
       .controlResponseChannel("aeron:udp?endpoint=localhost:0"));

if (!controlChannelEnabled && archiveClientContext.controlResponseChannel() == null)
{
    throw new IllegalArgumentException("controlResponseChannel required when controlChannelEnabled=false");
}

When it happens

Trigger: Launching Archive with .controlChannelEnabled(false) and no controlResponseChannel configured on the archiveClientContext.

Common situations: Disabling the external control request/response channels for a recording-only archive but forgetting that the internal client still needs a response channel setting.

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

• Aeron client instance must set…
• Aeron client must use a RethrowingErrorHandler
• segment file length not a power of 2
• segment file length not in valid range
• Unable to derive…

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

Appendix: source

Thrown at aeron-archive/src/main/java/io/aeron/archive/Archive.java:1545

                    if (null == endpoint || -1 == (separatorIndex = endpoint.lastIndexOf(':')))
                    {
                        throw new ConfigurationException(
                            "Unable to derive Archive.Context.archiveClientContext.controlResponseChannel as " +
                                "Archive.Context.controlChannel.endpoint=" + endpoint +
                                " and is not in the <host>:<port> format");
                    }

                    final String responseEndpoint = endpoint.substring(0, separatorIndex) + ":0";
                    final String responseChannel = new ChannelUriStringBuilder()
                        .media("udp")
                        .endpoint(responseEndpoint)
                        .build();

                    archiveClientContext.controlResponseChannel(responseChannel);
                }
                else
                {
                    throw new ConfigurationException(
                        "Archive.Context.archiveClientContext.controlResponseChannel must be set if " +
                            "Archive.Context.controlChannelEnabled is false"
                    );
                }
            }

            archiveClientContext
                .aeron(aeron)
                .lock(NoOpLock.INSTANCE)
                .errorHandler(errorHandler)
                .clientName(clientName);

            if (null == controlSessionsCounter)
            {
                controlSessionsCounter = ArchiveCounters.allocate(
                    aeron, tempBuffer, ARCHIVE_CONTROL_SESSIONS_TYPE_ID, "Archive Control Sessions", archiveId);
            }
            validateCounterTypeId(aeron, controlSessionsCounter, ARCHIVE_CONTROL_SESSIONS_TYPE_ID);

View on GitHub (pinned to 6d60124e15)