{"record":{"id":"8ef6b7e011ef5602","repo":"aeron-io/aeron","slug":"local-archive-control-must-be-ipc","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/ClusterBackup.java","lineNumber":866,"sourceCode":"\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            }\n\n            archiveContext\n                .aeron(aeron)\n                .errorHandler(errorHandler)\n                .ownsAeronClient(false)\n                .lock(NoOpLock.INSTANCE)\n                .clientName(clientName);\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 == clusterArchiveContext)\n            {\n                clusterArchiveContext = new AeronArchive.Context();\n            }\n\n            clusterArchiveContext\n                .aeron(aeron)\n                .ownsAeronClient(false)\n                .lock(NoOpLock.INSTANCE)\n                .clientName(clientName);\n","sourceCodeStart":848,"sourceCodeEnd":884,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-cluster/src/main/java/io/aeron/cluster/ClusterBackup.java#L848-L884","documentation":"When a cluster backup uses a local (in-process) Archive client, Context.conclude() enforces that the archive controlRequestChannel is an IPC (aeron:ipc) channel, since communication with a co-located archive must not go over the network. If the configured control request channel does not start with CommonContext.IPC_CHANNEL, it throws this ClusterException.","triggerScenarios":"Launching ClusterBackup with an AeronArchive.Context whose controlRequestChannel() is a UDP channel (e.g. aeron:udp?endpoint=...) while the backup is configured to use the local archive.","commonSituations":"Copy-pasting an archive context from a remote-client setup into a co-located cluster backup configuration.","solutions":["Set the archive context control channel to IPC: archiveContext.controlRequestChannel(CommonContext.IPC_CHANNEL) (optionally adding IPC session-specific params).","If remote control is truly required, reconfigure the backup to treat the archive as remote rather than local."],"exampleFix":"// before\narchiveContext.controlRequestChannel(\"aeron:udp?endpoint=localhost:8010\");\n// after\narchiveContext.controlRequestChannel(CommonContext.IPC_CHANNEL);","handlingStrategy":"validation","validationCode":"if (!archiveCtx.controlRequestChannel().startsWith(\"aeron:ipc\")) { throw new IllegalArgumentException(\"control request channel must be IPC for local archive\"); }","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use CommonContext.IPC_CHANNEL constant for local archive control channels","Review archive contexts copied from remote-client examples"],"tags":["aeron","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"}