aeron-io/aeron · error · ArchiveException

Aeron client instance must set…

Error message

Aeron client instance must set Aeron.Context.useConductorInvoker(true)

What it means

Archive requires its Aeron client to be created with Context.useConductorInvoker(true) so the archive's conductor agent can drive the client's conductor work without a separate thread. If the supplied Aeron client was built with the default (dedicated conductor thread) mode, Archive throws ArchiveException during startup. This is a deliberate configuration invariant, not a transient failure.

Solutions

1. Set useConductorInvoker(true) on the Aeron.Context used to create the client passed to Archive.
2. If the client must be shared with non-archive code, create a dedicated Aeron client for the archive with the invoker enabled.
3. Upgrade-related check: review migration notes if an older Aeron version did not require this setting.

Example fix

// before
Aeron aeron = Aeron.connect(new Aeron.Context());
Archive.launch(ctx.aeron(aeron));
// after
Aeron aeron = Aeron.connect(new Aeron.Context().useConductorInvoker(true));
Archive.launch(ctx.aeron(aeron));

if (!aeron.context().useConductorAgentInvoker())
{
    throw new IllegalArgumentException("Aeron client for Archive must use conductor agent invoker");
}

When it happens

Trigger: Passing an Aeron instance whose Aeon.Context has useConductorInvoker(false) (the default) to Archive.launch() or the Archive constructor with a pre-built client.

Common situations: Embedding Archive in an application that already created its Aeron client for normal pub/sub use and reuses it for the archive media driver; copying older sample code from before the invoker requirement was enforced.

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

• Aeron client must use a RethrowingErrorHandler
• segment file length not a power of 2
• segment file length not in valid range
• Unable to derive…
• Archive.Context.archiveClientContext.controlResponseChannel…

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

Appendix: source

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

                        .useConductorAgentInvoker(true)
                        .subscriberErrorHandler(RethrowingErrorHandler.INSTANCE)
                        .awaitingIdleStrategy(YieldingIdleStrategy.INSTANCE)
                        .clientLock(NoOpLock.INSTANCE)
                        .clientName(clientName));

                if (null == errorCounter)
                {
                    if (NULL_VALUE !=
                        ArchiveCounters.find(aeron.countersReader(), ARCHIVE_ERROR_COUNT_TYPE_ID, archiveId))
                    {
                        throw new ArchiveException("found existing archive for archiveId=" + archiveId);
                    }
                    errorCounter = ArchiveCounters.allocateErrorCounter(aeron, tempBuffer, archiveId);
                }
            }
            else if (!aeron.context().useConductorAgentInvoker())
            {
                throw new ArchiveException(
                    "Aeron client instance must set Aeron.Context.useConductorInvoker(true)");
            }

            if (!(aeron.context().subscriberErrorHandler() instanceof RethrowingErrorHandler))
            {
                throw new ArchiveException("Aeron client must use a RethrowingErrorHandler");
            }

            Objects.requireNonNull(errorCounter, "Error counter must be supplied if aeron client is");

            if (null == countedErrorHandler)
            {
                countedErrorHandler = new CountedErrorHandler(errorHandler, errorCounter);
            }

            if (null == threadFactory)
            {
                threadFactory = Thread::new;

View on GitHub (pinned to 6d60124e15)