{"record":{"id":"29249e4561e61e25","repo":"aeron-io/aeron","slug":"archive-context-replicationchannel-must-be-set","errorCode":null,"errorMessage":"Archive.Context.replicationChannel must be set","messagePattern":"Archive\\.Context\\.replicationChannel must be set","errorType":"validation","errorClass":"ConfigurationException","httpStatus":null,"severity":"error","filePath":"aeron-archive/src/main/java/io/aeron/archive/Archive.java","lineNumber":1237,"sourceCode":"                {\n                    throw new ConfigurationException(\"Archive.Context.controlChannel must be set\");\n                }\n\n                if (!controlChannel.startsWith(CommonContext.UDP_CHANNEL))\n                {\n                    throw new ConfigurationException(\n                        \"Archive.Context.controlChannel must be UDP media: uri=\" + controlChannel);\n                }\n            }\n\n            if (!localControlChannel.startsWith(CommonContext.IPC_CHANNEL))\n            {\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            {","sourceCodeStart":1219,"sourceCodeEnd":1255,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-archive/src/main/java/io/aeron/archive/Archive.java#L1219-L1255","documentation":"The archive listens on a replication channel so other archives can stream recordings to/from it; Archive.Context.replicationChannel was null when conclude() ran, so startup aborts with this ConfigurationException.","triggerScenarios":"Creating an Archive.Context without calling replicationChannel(...) while leaving replication enabled; environments where the aeron.archive.replication.channel property is absent and the code path constructs the context without Configuration defaults.","commonSituations":"Minimal archive setups that ignore replication features; upgrading Aeron and inheriting code written before replication configuration became required; stripped properties files.","solutions":["Call ctx.replicationChannel(\"aeron:udp?endpoint=0.0.0.0:8040\") on the context","Set the aeron.archive.replication.channel property","If replication is truly unused, verify your Aeron version/API whether a subscription-less setup allows omitting it; otherwise provide a valid URI"],"exampleFix":"// before\nArchive.Context ctx = new Archive.Context().controlChannel(\"aeron:udp?endpoint=0.0.0.0:8010\");\n// after\nArchive.Context ctx = new Archive.Context()\n    .controlChannel(\"aeron:udp?endpoint=0.0.0.0:8010\")\n    .replicationChannel(\"aeron:udp?endpoint=0.0.0.0:8040\");","handlingStrategy":"try-catch","validationCode":"if (ctx.replicationChannel() == null) {\n    throw new IllegalArgumentException(\"replicationChannel required\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    archive.start();\n} catch (ConfigurationException e) {\n    log.error(\"Missing archive configuration: {}\", e.getMessage());\n    throw e;\n}","preventionTips":["Set replicationChannel even if you do not use replication, unless your setup allows omission","Centralize archive context construction with all required channels","Keep properties files complete when copying between environments"],"tags":["configuration","aeron-archive","replication","missing-value"],"backgroundTag":"missing-required-config-field","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"}