{"record":{"id":"ee28e9a4354c1097","repo":"aeron-io/aeron","slug":"local-archive-control-must-be-ipc-consensusmodule","errorCode":null,"errorMessage":"local archive control must be IPC","messagePattern":"local archive control must be IPC","errorType":"validation","errorClass":"ClusterException","httpStatus":null,"severity":"error","filePath":"aeron-cluster/src/main/java/io/aeron/cluster/ConsensusModule.java","lineNumber":2083,"sourceCode":"\n            if (null == timerServiceSupplier)\n            {\n                timerServiceSupplier = getTimerServiceSupplierFromSystemProperty();\n            }\n\n            if (null == archiveContext)\n            {\n                archiveContext = new AeronArchive.Context()\n                    .controlRequestChannel(AeronArchive.Configuration.localControlChannel())\n                    .controlResponseChannel(AeronArchive.Configuration.localControlChannel())\n                    .controlRequestStreamId(AeronArchive.Configuration.localControlStreamId())\n                    .controlResponseStreamId(\n                        clusterId * 100 + 100 + AeronArchive.Configuration.controlResponseStreamId());\n            }\n\n            if (!archiveContext.controlRequestChannel().startsWith(CommonContext.IPC_CHANNEL))\n            {\n                throw new ClusterException(\"local archive control must be IPC\");\n            }\n\n            if (!archiveContext.controlResponseChannel().startsWith(CommonContext.IPC_CHANNEL))\n            {\n                throw new ClusterException(\"local archive control must be IPC\");\n            }\n\n            if (null == replicationChannel)\n            {\n                throw new ClusterException(\"replicationChannel must be set\");\n            }\n\n            archiveContext\n                .aeron(aeron)\n                .errorHandler(null) // ensure that exceptions are re-thrown\n                .ownsAeronClient(false)\n                .lock(NoOpLock.INSTANCE)\n                .controlRequestChannel(addAliasIfAbsent(","sourceCodeStart":2065,"sourceCodeEnd":2101,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-cluster/src/main/java/io/aeron/cluster/ConsensusModule.java#L2065-L2101","documentation":"The ConsensusModule lives in the same process as the local archive, so its archive control request channel must be the IPC channel (aeron:ipc) rather than a network channel. conclude() validates archiveContext.controlRequestChannel() and throws if it does not start with the IPCChannel prefix.","triggerScenarios":"Configuring ConsensusModule.Context.archiveContext() with an Archive.Context whose controlRequestChannel() is a network channel like 'aeron:udp?endpoint=localhost:8010'.","commonSituations":"Copying an archive configuration from a remote-archive client setup; setting archive control channels via properties or system properties meant for a standalone archive; misreading docs that the cluster's local archive must be accessed over IPC.","solutions":["Set the archive context control request channel to CommonContext.IPC_CHANNEL (\"aeron:ipc\").","If you rely on defaults, do not override archiveContext.controlRequestChannel() with a udp URI.","Check system properties (aeron.archive.control.channel etc.) that Archive.Context may pick up and override them for the cluster process."],"exampleFix":"// before\narchiveCtx.controlRequestChannel(\"aeron:udp?endpoint=localhost:8010\");\n// after\narchiveCtx.controlRequestChannel(CommonContext.IPC_CHANNEL); // \"aeron:ipc\"","handlingStrategy":"validation","validationCode":"if (!archiveCtx.controlRequestChannel().startsWith(CommonContext.IPC_CHANNEL)) {\n    throw new IllegalArgumentException(\"archive controlRequestChannel must be \" + CommonContext.IPC_CHANNEL);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always configure local archive control with aeron:ipc for cluster nodes","Never reuse remote archive-client channel configs inside the cluster process","Audit system properties that override archive control channels"],"tags":["aeron-cluster","configuration","archive","ipc"],"backgroundTag":"invalid-config-value","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"}