{"record":{"id":"c243a61cf229f76f","repo":"aeron-io/aeron","slug":"archive-context-recordingeventschannel-must-be-set-if","errorCode":null,"errorMessage":"Archive.Context.recordingEventsChannel must be set if Archive.Context.recordingEventsEnabled is true","messagePattern":"Archive\\.Context\\.recordingEventsChannel must be set if Archive\\.Context\\.recordingEventsEnabled is true","errorType":"validation","errorClass":"ConfigurationException","httpStatus":null,"severity":"error","filePath":"aeron-archive/src/main/java/io/aeron/archive/Archive.java","lineNumber":1242,"sourceCode":"                {\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            {\n                archiveDir = new File(archiveDirectoryName);\n            }\n\n            if (null == markFileDir)\n            {","sourceCodeStart":1224,"sourceCodeEnd":1260,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-archive/src/main/java/io/aeron/archive/Archive.java#L1224-L1260","documentation":"Recording event notifications are enabled (recordingEventsEnabled() is true) but the channel URI to publish those events on (recordingEventsChannel) is null. The archive has nowhere to send recording start/stop/progress events, so conclude() throws this ConfigurationException.","triggerScenarios":"Leaving recordingEventsEnabled at its default (true) while calling ctx.recordingEventsChannel(null) or never setting aeron.archive.recording.events.channel; programmatically enabling events without a channel.","commonSituations":"Minimal embedded-archive setups that never consume recording events; properties files that disable the events channel but not the enabled flag; code written against an older default where both defaulted off.","solutions":["Set the channel: ctx.recordingEventsChannel(\"aeron:ipc\") or a UDP endpoint like aeron:udp?endpoint=localhost:8011","Set the property aeron.archive.recording.events.channel","Disable events explicitly: ctx.recordingEventsEnabled(false) if nobody consumes them"],"exampleFix":"// before\nctx.recordingEventsEnabled(true);\n// after\nctx.recordingEventsEnabled(false);\n// or: ctx.recordingEventsChannel(\"aeron:ipc\");","handlingStrategy":"validation","validationCode":"if (ctx.recordingEventsEnabled() && ctx.recordingEventsChannel() == null) {\n    throw new IllegalArgumentException(\"recordingEventsChannel required when recordingEventsEnabled\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Disable recordingEventsEnabled(false) if no consumer of recording events exists","Pair every enable flag with its channel value in your config template","Use aeron:ipc for local-only event consumption to keep wiring simple"],"tags":["configuration","aeron-archive","recording-events","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"}