{"record":{"id":"9f4bcc361e0255f8","repo":"aeron-io/aeron","slug":"archive-context-threadingmode-archivethreadingmode-invoker","errorCode":null,"errorMessage":"Archive.Context.threadingMode(ArchiveThreadingMode.INVOKER) must be set if Archive.Context.mediaDriverAgentInvoker is set","messagePattern":"Archive\\.Context\\.threadingMode\\(ArchiveThreadingMode\\.INVOKER\\) must be set if Archive\\.Context\\.mediaDriverAgentInvoker is set","errorType":"validation","errorClass":"ConfigurationException","httpStatus":null,"severity":"error","filePath":"aeron-archive/src/main/java/io/aeron/archive/Archive.java","lineNumber":1249,"sourceCode":"            {\n                throw new ConfigurationException(\"local control channel must be IPC media: uri=\" + localControlChannel);\n            }\n\n            if (null == replicationChannel)\n            {\n                throw new ConfigurationException(\"Archive.Context.replicationChannel must be set\");\n            }\n\n            if (recordingEventsEnabled() && null == recordingEventsChannel())\n            {\n                throw new ConfigurationException(\n                    \"Archive.Context.recordingEventsChannel must be set if \" +\n                    \"Archive.Context.recordingEventsEnabled is true\");\n            }\n\n            if (null != mediaDriverAgentInvoker && ArchiveThreadingMode.INVOKER != threadingMode)\n            {\n                throw new ConfigurationException(\n                    \"Archive.Context.threadingMode(ArchiveThreadingMode.INVOKER) must be set if \" +\n                    \"Archive.Context.mediaDriverAgentInvoker is set\");\n            }\n\n            if (null == archiveDir)\n            {\n                archiveDir = new File(archiveDirectoryName);\n            }\n\n            if (null == markFileDir)\n            {\n                final String markFileDirPath = Configuration.markFileDir();\n                markFileDir = !Strings.isEmpty(markFileDirPath) ? new File(markFileDirPath) : archiveDir;\n            }\n\n            try\n            {\n                archiveDir = archiveDir.getCanonicalFile();","sourceCodeStart":1231,"sourceCodeEnd":1267,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-archive/src/main/java/io/aeron/archive/Archive.java#L1231-L1267","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Set ctx.threadingMode(ArchiveThreadingMode.INVOKER) when supplying an agent invoker","Remove the mediaDriverAgentInvoker(...) call if you want DEDICATED/SHARED threading","Set aeron.archive.threading.mode=INVOKER via properties"],"exampleFix":"// before\nctx.mediaDriverAgentInvoker(invoker); // threadingMode default DEDICATED\n// after\nctx.mediaDriverAgentInvoker(invoker).threadingMode(ArchiveThreadingMode.INVOKER);","handlingStrategy":"validation","validationCode":"if (ctx.mediaDriverAgentInvoker() != null && ctx.threadingMode() != ArchiveThreadingMode.INVOKER) {\n    throw new IllegalArgumentException(\"threadingMode must be INVOKER with an agent invoker\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Whenever you add mediaDriverAgentInvoker, set threadingMode(INVOKER) in the same line","Do not mix invoker mode with DEDICATED/SHARED threading assumptions","Review threading configuration when migrating between embedded and standalone setups"],"tags":["configuration","aeron-archive","threading","agent-invoker"],"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"}