aeron-io/aeron · error · ConfigurationException

Archive.Context.replicationChannel must be set

Error message

Archive.Context.replicationChannel must be set

What it means

The archive listens on a replication channel so other archives can stream recordings to/from it; Archive.Context.replicationChannel was null when conclude() ran, so startup aborts with this ConfigurationException.

Solutions

Call ctx.replicationChannel("aeron:udp?endpoint=0.0.0.0:8040") on the context
Set the aeron.archive.replication.channel property
If replication is truly unused, verify your Aeron version/API whether a subscription-less setup allows omitting it; otherwise provide a valid URI

Example fix

// before
Archive.Context ctx = new Archive.Context().controlChannel("aeron:udp?endpoint=0.0.0.0:8010");
// after
Archive.Context ctx = new Archive.Context()
    .controlChannel("aeron:udp?endpoint=0.0.0.0:8010")
    .replicationChannel("aeron:udp?endpoint=0.0.0.0:8040");

Defensive patterns

Strategy: try-catch

Validate before calling

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

Try / catch

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

Prevention

Set replicationChannel even if you do not use replication, unless your setup allows omission
Centralize archive context construction with all required channels
Keep properties files complete when copying between environments

When it happens

Trigger: Creating an Archive.Context without calling replicationChannel(...) while leaving replication enabled; environments where the aeron.archive.replication.channel property is absent and the code path constructs the context without Configuration defaults.

Common situations: Minimal archive setups that ignore replication features; upgrading Aeron and inheriting code written before replication configuration became required; stripped properties files.

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

Appendix: source

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

                {
                    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");
            }

            if (recordingEventsEnabled() && null == recordingEventsChannel())
            {
                throw new ConfigurationException(
                    "Archive.Context.recordingEventsChannel must be set if " +
                    "Archive.Context.recordingEventsEnabled is true");
            }

            if (null != mediaDriverAgentInvoker && ArchiveThreadingMode.INVOKER != threadingMode)
            {
                throw new ConfigurationException(
                    "Archive.Context.threadingMode(ArchiveThreadingMode.INVOKER) must be set if " +
                    "Archive.Context.mediaDriverAgentInvoker is set");
            }

            if (null == archiveDir)
            {

View on GitHub (pinned to 6d60124e15)