aeron-io/aeron · error · ConfigurationException

local control channel must be IPC media: uri=

Error message

local control channel must be IPC media: uri=${localControlChannel}

What it means

The archive's local control channel is used for same-host IPC communication and must be an aeron:ipc URI. conclude() throws this ConfigurationException when the provided URI is not IPC (e.g. a UDP URI was supplied).

Solutions

1. Set localControlChannel to "aeron:ipc"
2. Use UDP URIs only for controlChannel and replicationChannel
3. Check that controlChannel/localControlChannel were not swapped in your config

Example fix

// before
ctx.localControlChannel("aeron:udp?endpoint=localhost:8011")
// after
ctx.localControlChannel("aeron:ipc")

if (!ctx.localControlChannel().startsWith("aeron:ipc")) {
    throw new IllegalArgumentException("localControlChannel must be aeron:ipc");
}

When it happens

Trigger: Setting localControlChannel to aeron:udp?endpoint=... instead of aeron:ipc; swapping the controlChannel and localControlChannel values when configuring the archive.

Common situations: Copy-paste of the remote control channel URI into the local one; operators changing the local channel to UDP expecting better tooling access; template configs with the fields in the wrong order.

Understand the failure class

Background: "Invalid URL" errors: why new URL(), URI.parse, and reqwest::Url reject your string — missing scheme, whitespace, and bad path format — this error's family across 39 libraries.

Related errors

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

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

Appendix: source

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

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

            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 " +

View on GitHub (pinned to 6d60124e15)