{"record":{"id":"b5c95d081966cf75","repo":"aeron-io/aeron","slug":"archive-context-controlchannel-must-be-udp-media-uri","errorCode":null,"errorMessage":"Archive.Context.controlChannel must be UDP media: uri=${controlChannel}","messagePattern":"Archive\\.Context\\.controlChannel must be UDP media: uri=(.+?)","errorType":"validation","errorClass":"ConfigurationException","httpStatus":null,"severity":"error","filePath":"aeron-archive/src/main/java/io/aeron/archive/Archive.java","lineNumber":1225,"sourceCode":"\n            if (fileIoMaxLength < TERM_MIN_LENGTH || !BitUtil.isPowerOfTwo(fileIoMaxLength))\n            {\n                throw new ConfigurationException(\"invalid fileIoMaxLength=\" + fileIoMaxLength);\n            }\n\n            io.aeron.driver.Configuration.validateMtuLength(controlMtuLength);\n            checkTermLength(controlTermBufferLength);\n\n            if (controlChannelEnabled)\n            {\n                if (null == controlChannel)\n                {\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 \" +","sourceCodeStart":1207,"sourceCodeEnd":1243,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-archive/src/main/java/io/aeron/archive/Archive.java#L1207-L1243","documentation":"Archive.controlChannel must be an aeron:udp URI, but a URI starting with something else (e.g. aeron:ipc or a malformed string) was supplied. The archive control endpoint uses unicast/multicast UDP so remote clients can connect; conclude() rejects anything else.","triggerScenarios":"Passing an IPC channel URI (aeron:ipc) to controlChannel; typo in the URI scheme such as 'aeron:udp endpoint=...' without the '?' or missing endpoint parameter so startsWith(CommonContext.UDP_CHANNEL) fails.","commonSituations":"Copy-pasting the localControlChannel (which must be IPC) into controlChannel; hand-editing channel URIs and breaking the prefix; environment-specific property files with malformed URIs.","solutions":["Set controlChannel to a UDP URI, e.g. aeron:udp?endpoint=0.0.0.0:8010","Use an IPC URI only for localControlChannel, not controlChannel","Validate the URI string starts with 'aeron:udp' before calling ctx.controlChannel(...)"],"exampleFix":"// before\nctx.controlChannel(\"aeron:ipc\")\n// after\nctx.controlChannel(\"aeron:udp?endpoint=0.0.0.0:8010\")","handlingStrategy":"validation","validationCode":"if (!ctx.controlChannel().startsWith(\"aeron:udp\")) {\n    throw new IllegalArgumentException(\"controlChannel must be aeron:udp\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Remember: controlChannel=UDP, localControlChannel=IPC","Validate Aeron URIs (scheme prefix) in your config loader","Reuse constants CommonContext.UDP_CHANNEL / IPC_CHANNEL instead of raw strings"],"tags":["configuration","aeron-archive","udp-channel","uri-format"],"backgroundTag":"invalid-url-format","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"}