{"record":{"id":"7cac04474f2f183f","repo":"aeron-io/aeron","slug":"must-use-aeron-context-useconductoragentinvoker-true-when-7cac04","errorCode":null,"errorMessage":"Must use Aeron.Context.useConductorAgentInvoker(true) when Aeron.Context.driverAgentInvoker() is set","messagePattern":"Must use Aeron\\.Context\\.useConductorAgentInvoker\\(true\\) when Aeron\\.Context\\.driverAgentInvoker\\(\\) is set","errorType":"validation","errorClass":"ConfigurationException","httpStatus":null,"severity":"error","filePath":"aeron-client/src/main/java/io/aeron/Aeron.java","lineNumber":1191,"sourceCode":"        @SuppressWarnings(\"checkstyle:methodlength\")\n        public Context conclude()\n        {\n            super.conclude();\n\n            if (null == clientLock)\n            {\n                clientLock = new ReentrantLock();\n            }\n            else if (clientLock instanceof NoOpLock && !useConductorAgentInvoker)\n            {\n                throw new ConfigurationException(\n                    \"Must use Aeron.Context.useConductorAgentInvoker(true) when Aeron.Context.clientLock(...) \" +\n                    \"is using a NoOpLock\");\n            }\n\n            if (null != driverAgentInvoker && !useConductorAgentInvoker)\n            {\n                throw new ConfigurationException(\n                    \"Must use Aeron.Context.useConductorAgentInvoker(true) when Aeron.Context.driverAgentInvoker() \" +\n                    \"is set\");\n            }\n\n            if (clientName.length() > MAX_CLIENT_NAME_LENGTH)\n            {\n                throw new ConfigurationException(\"clientName length must <= \" + MAX_CLIENT_NAME_LENGTH);\n            }\n\n            if (null == epochClock)\n            {\n                epochClock = SystemEpochClock.INSTANCE;\n            }\n\n            if (null == nanoClock)\n            {\n                nanoClock = SystemNanoClock.INSTANCE;\n            }","sourceCodeStart":1173,"sourceCodeEnd":1209,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-client/src/main/java/io/aeron/Aeron.java#L1173-L1209","documentation":"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.","triggerScenarios":"Building a Context with ctx.driverAgentInvoker(driverAgentInvoker) while leaving useConductorAgentInvoker at its default (false), then calling Aeron.connect(ctx).","commonSituations":"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.","solutions":["Add ctx.useConductorAgentInvoker(true) to the Context when passing a driverAgentInvoker","Remove the driverAgentInvoker() call if the client should run its own conductor thread (standalone mode)","Ensure the invoker is actually driven in a loop on the shared thread after connecting"],"exampleFix":"// before\nAeron.Context ctx = new Aeron.Context()\n    .driverAgentInvoker(driverAgentInvoker); // throws\n// after\nAeron.Context ctx = new Aeron.Context()\n    .driverAgentInvoker(driverAgentInvoker)\n    .useConductorAgentInvoker(true);","handlingStrategy":"validation","validationCode":"if (driverAgentInvoker != null) { ctx.useConductorAgentInvoker(true); }","typeGuard":"boolean invokerModeConsistent(Aeron.Context ctx) { return ctx.useConductorAgentInvoker() || ctx.driverAgentInvoker() == null; }","tryCatchPattern":"try { return Aeron.connect(ctx); } catch (ConfigurationException e) { if (e.getMessage().contains(\"driverAgentInvoker\")) { ctx.useConductorAgentInvoker(true); return Aeron.connect(ctx); } throw e; }","preventionTips":["Set useConductorAgentInvoker(true) whenever you pass a driverAgentInvoker","Centralize embedded-driver client construction in a helper","Ensure the invoker is driven in a loop on the shared thread after connect"],"tags":["configuration","agent-invoker","embedded-driver","conflicting-options"],"backgroundTag":"conflicting-config-options","analyzedSha":"6d60124e15e35c11b49ba2e3c2c2858a09a18803","analyzedAt":"2026-09-12T11:17:07.683Z","contentChangedAt":"2026-09-12T11:17:07.683Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}