aeron-io/aeron · error · ClusterException

local archive control must be IPC

Error message

local archive control must be IPC

What it means

When a cluster backup uses a local (in-process) Archive client, Context.conclude() enforces that the archive controlRequestChannel is an IPC (aeron:ipc) channel, since communication with a co-located archive must not go over the network. If the configured control request channel does not start with CommonContext.IPC_CHANNEL, it throws this ClusterException.

Solutions

1. Set the archive context control channel to IPC: archiveContext.controlRequestChannel(CommonContext.IPC_CHANNEL) (optionally adding IPC session-specific params).
2. If remote control is truly required, reconfigure the backup to treat the archive as remote rather than local.

Example fix

// before
archiveContext.controlRequestChannel("aeron:udp?endpoint=localhost:8010");
// after
archiveContext.controlRequestChannel(CommonContext.IPC_CHANNEL);

if (!archiveCtx.controlRequestChannel().startsWith("aeron:ipc")) { throw new IllegalArgumentException("control request channel must be IPC for local archive"); }

When it happens

Trigger: Launching ClusterBackup with an AeronArchive.Context whose controlRequestChannel() is a UDP channel (e.g. aeron:udp?endpoint=...) while the backup is configured to use the local archive.

Common situations: Copy-pasting an archive context from a remote-client setup into a co-located cluster backup configuration.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• local archive control must be IPC
• 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

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

Appendix: source

Thrown at aeron-cluster/src/main/java/io/aeron/cluster/ClusterBackup.java:866

            if (null == archiveContext)
            {
                archiveContext = new AeronArchive.Context()
                    .controlRequestChannel(AeronArchive.Configuration.localControlChannel())
                    .controlResponseChannel(AeronArchive.Configuration.localControlChannel())
                    .controlRequestStreamId(AeronArchive.Configuration.localControlStreamId());
            }

            archiveContext
                .aeron(aeron)
                .errorHandler(errorHandler)
                .ownsAeronClient(false)
                .lock(NoOpLock.INSTANCE)
                .clientName(clientName);

            if (!archiveContext.controlRequestChannel().startsWith(CommonContext.IPC_CHANNEL))
            {
                throw new ClusterException("local archive control must be IPC");
            }

            if (!archiveContext.controlResponseChannel().startsWith(CommonContext.IPC_CHANNEL))
            {
                throw new ClusterException("local archive control must be IPC");
            }

            if (null == clusterArchiveContext)
            {
                clusterArchiveContext = new AeronArchive.Context();
            }

            clusterArchiveContext
                .aeron(aeron)
                .ownsAeronClient(false)
                .lock(NoOpLock.INSTANCE)
                .clientName(clientName);

View on GitHub (pinned to 6d60124e15)