aeron-io/aeron · error · ConfigurationException

Archive.Context.controlChannel must be set

Error message

Archive.Context.controlChannel must be set

What it means

When controlChannelEnabled is true the archive needs a control request channel URI to listen on, but Archive.Context.controlChannel is null. The archive cannot accept client control sessions without it, so conclude() fails fast with this ConfigurationException.

Solutions

  1. Call ctx.controlChannel("aeron:udp?endpoint=localhost:8010") before concluding the context
  2. Set the system/properties value aeron.archive.control.channel
  3. Call ctx.controlChannelEnabled(false) if the control endpoint is intentionally not used

Example fix

// before
Archive.Context ctx = new Archive.Context();
// after
Archive.Context ctx = new Archive.Context()
    .controlChannel("aeron:udp?endpoint=localhost:8010");
Defensive patterns

Strategy: try-catch

Validate before calling

if (ctx.controlChannelEnabled() && ctx.controlChannel() == null) {
    throw new IllegalArgumentException("controlChannel required when controlChannelEnabled");
}

Try / catch

try {
    archive.start();
} catch (ConfigurationException e) {
    log.error("Archive configuration invalid: {}", e.getMessage());
    throw e;
}

Prevention

When it happens

Trigger: Building Archive.Context with controlChannelEnabled(true) (or default enabled) and never calling controlChannel(...); constructing the context programmatically without the corresponding aeron.archive.control.channel property being present.

Common situations: Programmatic Archive.Context setup where the property was assumed to fill in defaults; disabling properties file loading so Configuration defaults that normally derive from system properties are skipped; refactors that remove controlChannel(...) while keeping events/replication wiring.

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

Appendix: source

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

            if (catalogFileSyncLevel < fileSyncLevel)
            {
                throw new ConfigurationException(
                    "catalogFileSyncLevel " + catalogFileSyncLevel + " < fileSyncLevel " + fileSyncLevel);
            }

            if (fileIoMaxLength < TERM_MIN_LENGTH || !BitUtil.isPowerOfTwo(fileIoMaxLength))
            {
                throw new ConfigurationException("invalid fileIoMaxLength=" + fileIoMaxLength);
            }

            io.aeron.driver.Configuration.validateMtuLength(controlMtuLength);
            checkTermLength(controlTermBufferLength);

            if (controlChannelEnabled)
            {
                if (null == controlChannel)
                {
                    throw new ConfigurationException("Archive.Context.controlChannel must be set");
                }

                if (!controlChannel.startsWith(CommonContext.UDP_CHANNEL))
                {
                    throw new ConfigurationException(
                        "Archive.Context.controlChannel must be UDP media: uri=" + controlChannel);
                }
            }

            if (!localControlChannel.startsWith(CommonContext.IPC_CHANNEL))
            {
                throw new ConfigurationException("local control channel must be IPC media: uri=" + localControlChannel);
            }

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

View on GitHub (pinned to 6d60124e15)