{"record":{"id":"da6f62a84a830e2e","repo":"aeron-io/aeron","slug":"local-archive-control-must-be-ipc-clusteredservicecontainer","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/service/ClusteredServiceContainer.java","lineNumber":1023,"sourceCode":"                        clusterId,\n                        serviceId\n                    ),\n                    snapshotDurationThresholdNs);\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() + (serviceId + 1));\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            archiveContext\n                .aeron(aeron)\n                .ownsAeronClient(false)\n                .lock(NoOpLock.INSTANCE)\n                .errorHandler(null) // propagate errors directly\n                .controlRequestChannel(addAliasIfAbsent(\n                archiveContext.controlRequestChannel(),\n                \"sc-\" + serviceId + \"-archive-ctrl-req-cluster-\" + clusterId))\n                .controlResponseChannel(addAliasIfAbsent(\n                archiveContext.controlResponseChannel(),\n                \"sc-\" + serviceId + \"-archive-ctrl-resp-cluster-\" + clusterId))","sourceCodeStart":1005,"sourceCodeEnd":1041,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-cluster/src/main/java/io/aeron/cluster/service/ClusteredServiceContainer.java#L1005-L1041","documentation":"ClusteredServiceContainer requires that when a clustered service runs in the same JVM as the archive (local archive), the AeronArchive control request and response channels must use the IPC protocol (aeron:ipc) instead of a network transport. This avoids inter-JVM hops for archive control within the cluster node. If either channel is not IPC, a ClusterException is thrown during Context configuration.","triggerScenarios":"Configuring ClusteredServiceContainer.Context with an archiveContext whose controlRequestChannel() or controlResponseChannel() does not start with 'aeron:ipc' while the container expects a local (embedded) archive.","commonSituations":"Pointing the cluster's archive context at a remote archive via UDP channels; copying archive channel config from a standalone (non-cluster) example; setting AERON_ARCHIVE_CONTROL_CHANNEL env/config to a network channel instead of aeron:ipc.","solutions":["Set the archive control request channel to 'aeron:ipc' (e.g. archiveContext.controlRequestChannel(CommonContext.IPC_CHANNEL)).","Set the archive control response channel to 'aeron:ipc' as well.","If the archive is genuinely remote, embed a local archive for the cluster node instead of reusing a remote one.","Check cluster directory / system properties (aeron.archive.control.* overrides) for values forcing network channels."],"exampleFix":"// before\narchiveContext.controlRequestChannel(\"aeron:udp?endpoint=localhost:8010\");\n// after\narchiveContext.controlRequestChannel(CommonContext.IPC_CHANNEL);\narchiveContext.controlResponseChannel(CommonContext.IPC_CHANNEL);","handlingStrategy":"validation","validationCode":"if (!archiveContext.controlRequestChannel().startsWith(\"aeron:ipc\")) {\n    archiveContext.controlRequestChannel(\"aeron:ipc\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always use CommonContext.IPC_CHANNEL constant, never string literals, for local archive channels.","Do not copy archive channel settings from standalone archive clients into cluster service containers.","Unit-test container Context configuration in CI to catch channel misconfig before runtime."],"tags":["aeron","archive","ipc","configuration"],"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"}