aeron-io/aeron · error · ConfigurationException

Archive.Context.recordingEventsChannel must be set if…

Error message

Archive.Context.recordingEventsChannel must be set if Archive.Context.recordingEventsEnabled is true

What it means

Recording event notifications are enabled (recordingEventsEnabled() is true) but the channel URI to publish those events on (recordingEventsChannel) is null. The archive has nowhere to send recording start/stop/progress events, so conclude() throws this ConfigurationException.

Solutions

1. Set the channel: ctx.recordingEventsChannel("aeron:ipc") or a UDP endpoint like aeron:udp?endpoint=localhost:8011
2. Set the property aeron.archive.recording.events.channel
3. Disable events explicitly: ctx.recordingEventsEnabled(false) if nobody consumes them

Example fix

// before
ctx.recordingEventsEnabled(true);
// after
ctx.recordingEventsEnabled(false);
// or: ctx.recordingEventsChannel("aeron:ipc");

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

When it happens

Trigger: Leaving recordingEventsEnabled at its default (true) while calling ctx.recordingEventsChannel(null) or never setting aeron.archive.recording.events.channel; programmatically enabling events without a channel.

Common situations: Minimal embedded-archive setups that never consume recording events; properties files that disable the events channel but not the enabled flag; code written against an older default where both defaulted off.

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

• Archive.Context.controlChannel must be set
• Archive.Context.replicationChannel must be set
• catalogFileSyncLevel
• invalid fileIoMaxLength=
• Archive.Context.controlChannel must be UDP media: uri=

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

Appendix: source

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

                {
                    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)
            {
                archiveDir = new File(archiveDirectoryName);
            }

            if (null == markFileDir)
            {

View on GitHub (pinned to 6d60124e15)