aeron-io/aeron · error · ConfigurationException

Must use Aeron.Context.useConductorAgentInvoker(true) when…

Error message

Must use Aeron.Context.useConductorAgentInvoker(true) when Aeron.Context.driverAgentInvoker() is set

What it means

Aeron.Context throws this ConfigurationException when a driverAgentInvoker has been set via driverAgentInvoker(...) but useConductorAgentInvoker(true) was not enabled. Sharing the driver agent invoker only makes sense when the client conductor is also driven by the invoking thread; otherwise the two agents would be driven from different threads unsafely, so the configuration is rejected.

Solutions

  1. Add ctx.useConductorAgentInvoker(true) to the Context when passing a driverAgentInvoker
  2. Remove the driverAgentInvoker() call if the client should run its own conductor thread (standalone mode)
  3. Ensure the invoker is actually driven in a loop on the shared thread after connecting

Example fix

// before
Aeron.Context ctx = new Aeron.Context()
    .driverAgentInvoker(driverAgentInvoker); // throws
// after
Aeron.Context ctx = new Aeron.Context()
    .driverAgentInvoker(driverAgentInvoker)
    .useConductorAgentInvoker(true);
Defensive patterns

Strategy: validation

Validate before calling

if (driverAgentInvoker != null) { ctx.useConductorAgentInvoker(true); }

Type guard

boolean invokerModeConsistent(Aeron.Context ctx) { return ctx.useConductorAgentInvoker() || ctx.driverAgentInvoker() == null; }

Try / catch

try { return Aeron.connect(ctx); } catch (ConfigurationException e) { if (e.getMessage().contains("driverAgentInvoker")) { ctx.useConductorAgentInvoker(true); return Aeron.connect(ctx); } throw e; }

Prevention

When it happens

Trigger: Building a Context with ctx.driverAgentInvoker(driverAgentInvoker) while leaving useConductorAgentInvoker at its default (false), then calling Aeron.connect(ctx).

Common situations: Embedded/dedicated-mode setups where the application drives the MediaDriver agent itself and wants the client embedded too, but forgot to enable conductor agent invoker mode; partial migration from standalone driver to embedded mode.

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/7cac04474f2f183f. Report an issue: GitHub.

Appendix: source

Thrown at aeron-client/src/main/java/io/aeron/Aeron.java:1191

        @SuppressWarnings("checkstyle:methodlength")
        public Context conclude()
        {
            super.conclude();

            if (null == clientLock)
            {
                clientLock = new ReentrantLock();
            }
            else if (clientLock instanceof NoOpLock && !useConductorAgentInvoker)
            {
                throw new ConfigurationException(
                    "Must use Aeron.Context.useConductorAgentInvoker(true) when Aeron.Context.clientLock(...) " +
                    "is using a NoOpLock");
            }

            if (null != driverAgentInvoker && !useConductorAgentInvoker)
            {
                throw new ConfigurationException(
                    "Must use Aeron.Context.useConductorAgentInvoker(true) when Aeron.Context.driverAgentInvoker() " +
                    "is set");
            }

            if (clientName.length() > MAX_CLIENT_NAME_LENGTH)
            {
                throw new ConfigurationException("clientName length must <= " + MAX_CLIENT_NAME_LENGTH);
            }

            if (null == epochClock)
            {
                epochClock = SystemEpochClock.INSTANCE;
            }

            if (null == nanoClock)
            {
                nanoClock = SystemNanoClock.INSTANCE;
            }

View on GitHub (pinned to 6d60124e15)