aeron-io/aeron · error · ConfigurationException

Archive.Context.threadingMode(ArchiveThreadingMode.INVOKER)…

Error message

Archive.Context.threadingMode(ArchiveThreadingMode.INVOKER) must be set if Archive.Context.mediaDriverAgentInvoker is set

What it means

A media driver AgentInvoker was supplied via Archive.Context.mediaDriverAgentInvoker, but threadingMode is not ArchiveThreadingMode.INVOKER. The invoker pattern only works when the archive runs all its agents on the caller's thread via the invoker, so conclude() rejects any other threading mode as contradictory.

Solutions

1. Set ctx.threadingMode(ArchiveThreadingMode.INVOKER) when supplying an agent invoker
2. Remove the mediaDriverAgentInvoker(...) call if you want DEDICATED/SHARED threading
3. Set aeron.archive.threading.mode=INVOKER via properties

Example fix

// before
ctx.mediaDriverAgentInvoker(invoker); // threadingMode default DEDICATED
// after
ctx.mediaDriverAgentInvoker(invoker).threadingMode(ArchiveThreadingMode.INVOKER);

if (ctx.mediaDriverAgentInvoker() != null && ctx.threadingMode() != ArchiveThreadingMode.INVOKER) {
    throw new IllegalArgumentException("threadingMode must be INVOKER with an agent invoker");
}

When it happens

Trigger: ctx.mediaDriverAgentInvoker(driverInvoker) with threadingMode left at default (DEDICATED) or set to SHARED/SHARED_NETWORK; combining an embedded driver's invoker with a separately-threaded archive.

Common situations: Low-latency setups adopting AgentInvoker for the driver and archive but updating only one side of the configuration; migration from DEDICATED threading to invoker-based threading done partially.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

• Aeron client must use conductor agent invoker
• catalogFileSyncLevel
• invalid fileIoMaxLength=
• Archive.Context.controlChannel must be set
• Archive.Context.controlChannel must be UDP media: uri=

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

Appendix: source

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

            {
                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)
            {
                final String markFileDirPath = Configuration.markFileDir();
                markFileDir = !Strings.isEmpty(markFileDirPath) ? new File(markFileDirPath) : archiveDir;
            }

            try
            {
                archiveDir = archiveDir.getCanonicalFile();

View on GitHub (pinned to 6d60124e15)