aeron-io/aeron · error · ClusterException

Aeron client must use conductor agent invoker

Error message

Aeron client must use conductor agent invoker

What it means

ClusterBackup must interact with the Aeron client via the conductor agent invoker so client conductor work runs on the backup agent's thread rather than a separate client conductor thread. conclude() throws this ClusterException when the supplied Aeron context does not enable useConductorAgentInvoker().

Solutions

  1. Create the Aeron client with context.useConductorAgentInvoker(true) and drive it via aeron.conductorAgentInvoker() inside the backup agent.
  2. Use a dedicated Aeron client for ClusterBackup instead of reusing an application client with a conductor thread.
  3. Review Aeron cluster samples (ClusterBackup) for the canonical client setup.

Example fix

// before
Aeron aeron = Aeron.connect(new Aeron.Context());
// after
Aeron aeron = Aeron.connect(new Aeron.Context().useConductorAgentInvoker(true));
Defensive patterns

Strategy: validation

Validate before calling

if (!aeronCtx.useConductorAgentInvoker()) { throw new IllegalStateException("backup requires conductor agent invoker"); }

Type guard

static boolean usesAgentInvoker(Aeron.Context c) { return c.useConductorAgentInvoker(); }

Try / catch

try {
    ctx.conclude();
} catch (ClusterException e) {
    if (e.getMessage().contains("conductor agent invoker")) { log.error("call Aeron.Context.useConductorAgentInvoker(true)"); }
    throw e;
}

Prevention

When it happens

Trigger: Concluding a ClusterBackup.Context with an Aeron client created from a context where aeron.context().useConductorAgentInvoker() is false (the default is a dedicated client conductor thread).

Common situations: Reusing a shared Aeron client built for normal (threaded) usage; forgetting clientContext.useConductorAgentInvoker(true) when setting up a dedicated client for the backup agent.

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

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

Appendix: source

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

                    errorCounter = ClusterCounters.allocateVersioned(
                        aeron,
                        buffer,
                        "ClusterBackup Errors",
                        CLUSTER_BACKUP_ERROR_COUNT_TYPE_ID,
                        clusterId,
                        ClusterBackupVersion.VERSION,
                        ClusterBackupVersion.GIT_SHA);
                }
            }

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

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

            if (null == errorCounter)
            {
                throw new ClusterException("error counter must be supplied if aeron client is");
            }

            if (null == countedErrorHandler)
            {
                countedErrorHandler = new CountedErrorHandler(errorHandler, errorCounter);
                if (ownsAeronClient)
                {
                    aeron.context().errorHandler(countedErrorHandler);
                }
            }

            if (null == stateCounter)
            {

View on GitHub (pinned to 6d60124e15)