{"record":{"id":"496a55e88355ad68","repo":"aeron-io/aeron","slug":"control-mode-dynamic-requires-that-control-parameter-is-set","errorCode":null,"errorMessage":"'control-mode=dynamic' requires that 'control' parameter is set, channel=${originalUriString}","messagePattern":"'control-mode=dynamic' requires that 'control' parameter is set, channel=(.+?)","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"aeron-driver/src/main/java/io/aeron/driver/DriverConductor.java","lineNumber":2337,"sourceCode":"                    \": existingChannel=\" + existingChannel + \" channel=\" + channel);\n        }\n    }\n\n    private static void validateEndpointForPublication(final UdpChannel udpChannel)\n    {\n        if (!udpChannel.isMultiDestination() && udpChannel.hasExplicitEndpoint() &&\n            0 == udpChannel.remoteData().getPort())\n        {\n            throw new IllegalArgumentException(\n                ENDPOINT_PARAM_NAME + \" has port=0 for publication: channel=\" + udpChannel.originalUriString());\n        }\n    }\n\n    private static void validateControlForPublication(final UdpChannel udpChannel)\n    {\n        if (udpChannel.isDynamicControlMode() && !udpChannel.hasExplicitControl())\n        {\n            throw new IllegalArgumentException(\n                \"'control-mode=dynamic' requires that 'control' parameter is set, channel=\" +\n                    udpChannel.originalUriString());\n        }\n\n        if (udpChannel.hasExplicitControl() && !udpChannel.hasExplicitEndpoint() &&\n            ControlMode.NONE == udpChannel.controlMode())\n        {\n            throw new IllegalArgumentException(\n                \"'control' parameter requires that either 'endpoint' or 'control-mode' is specified, channel=\" +\n                    udpChannel.originalUriString());\n        }\n    }\n\n    private static void validateControlForSubscription(final UdpChannel udpChannel)\n    {\n        if (udpChannel.hasExplicitControl() &&\n            0 == udpChannel.localControl().getPort())\n        {","sourceCodeStart":2319,"sourceCodeEnd":2355,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-driver/src/main/java/io/aeron/driver/DriverConductor.java#L2319-L2355","documentation":"'control-mode=dynamic' multi-destination-cast publications need a concrete 'control' address that receivers subscribe to; without it the driver cannot bind the control endpoint. This IllegalArgumentException is thrown when a publication URI sets control-mode=dynamic but has no explicit control parameter.","triggerScenarios":"addPublication with \"aeron:udp?control-mode=dynamic\" but no control=host:port; building MDC URIs where the control parameter is dropped by a template; renaming mistakes (ctrl vs control).","commonSituations":"Misconfigured MDC setup where senders specify dynamic control mode but forget the control address; docs/examples partially copied; env-driven URI assembly losing the control param.","solutions":["Add control=host:port to the publication URI alongside control-mode=dynamic","Or use control-mode=manual if destinations are added programmatically instead","Remove control-mode=dynamic if unicast endpoint publication was intended"],"exampleFix":"// before\naeron.addPublication(\"aeron:udp?control-mode=dynamic\", 1001);\n// after\naeron.addPublication(\"aeron:udp?control=localhost:40456|control-mode=dynamic\", 1001);","handlingStrategy":"validation","validationCode":"if (\"dynamic\".equals(uriParam(channel, \"control-mode\", null)) && uriParam(channel, \"control\", null) == null) {\n    throw new IllegalArgumentException(\"control-mode=dynamic requires control= : \" + channel);\n}","typeGuard":null,"tryCatchPattern":"try { aeron.addPublication(channel, streamId); } catch (IllegalArgumentException e) { if (e.getMessage().contains(\"'control-mode=dynamic' requires\")) { log.error(\"add control= to {}\", channel); } throw e; }","preventionTips":["Always pair control-mode=dynamic with an explicit control= address","Use a validated MDC URI builder","Unit-test channel URI templates for required param pairs"],"tags":["aeron","uri","mdc","channel-config"],"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"}