{"record":{"id":"9bcc0205ffebf81f","repo":"aeron-io/aeron","slug":"control-has-port-0-for-subscription-channel-channel","errorCode":null,"errorMessage":"control has port=0 for subscription: channel={channel}","messagePattern":"control has port=0 for subscription: channel=(.+?)","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"aeron-driver/src/main/java/io/aeron/driver/DriverConductor.java","lineNumber":2356,"sourceCode":"                \"'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        {\n            throw new IllegalArgumentException(MDC_CONTROL_PARAM_NAME + \" has port=0 for subscription: channel=\" +\n                udpChannel.originalUriString());\n        }\n    }\n\n    private static void validateTimestampConfiguration(final UdpChannel udpChannel)\n    {\n        if (null != udpChannel.channelUri().get(MEDIA_RCV_TIMESTAMP_OFFSET_PARAM_NAME))\n        {\n            throw new InvalidChannelException(\n                \"Media timestamps '\" + MEDIA_RCV_TIMESTAMP_OFFSET_PARAM_NAME +\n                    \"' are not supported in the Java driver: channel=\" + udpChannel.originalUriString());\n        }\n    }\n\n    private static void validateDestinationUri(final ChannelUri uri, final String destinationUri)\n    {\n        if (SPY_QUALIFIER.equals(uri.prefix()))\n        {","sourceCodeStart":2338,"sourceCodeEnd":2374,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-driver/src/main/java/io/aeron/driver/DriverConductor.java#L2338-L2374","documentation":"The Java Aeron driver rejects a subscription whose channel URI specifies an explicit control address with port 0. For subscriptions, the explicit control endpoint must have a concrete (non-zero) port so the driver knows where to receive control/setup traffic. This static validation runs in DriverConductor when a network publication or subscription is being added.","triggerScenarios":"Calling Aeron.addSubscription() (or a destination variant) with a channel URI like \"aeron:udp?control=hostname|control-port=0\" (an explicit control-mode=manual/manual multicast or MDC control address with port 0).","commonSituations":"Copy-pasting a publication URI (where port 0 can be legal for an ephemeral control port) into a subscription; templated configs where the control-port placeholder was never filled in; MDC setup where the control endpoint was confused with the data endpoint.","solutions":["Set an explicit non-zero control-port in the channel URI (e.g. control-mode=manual|control=localhost:40456).","Remove the explicit control address if you do not need MDC and rely on the default control channel instead.","For publications-only, leave port 0 (dynamic control port) but never on the subscription side.","Add a config validation step that parses the URI and checks control-port != 0 before calling addSubscription()."],"exampleFix":"// before\nString uri = \"aeron:udp?control=224.0.1.1:0|control-mode=manual\";\naeron.addSubscription(uri, 1001);\n// after\nString uri = \"aeron:udp?interface=0.0.0.0:0|control=224.0.1.1:40456|control-mode=manual\";\naeron.addSubscription(uri, 1001);","handlingStrategy":"validation","validationCode":"ChannelUri uri = ChannelUri.parse(channel);\nString control = uri.get(\"control\");\nif (control != null && control.endsWith(\":0\")) throw new IllegalArgumentException(\"control must not use port 0 for subscriptions\");","typeGuard":"boolean hasValidControlPort(ChannelUri uri) {\n  String c = uri.get(\"control\");\n  return c == null || !c.endsWith(\":0\");\n}","tryCatchPattern":"try { aeron.addSubscription(uri, streamId); }\ncatch (IllegalArgumentException e) { if (e.getMessage().contains(\"port=0 for subscription\")) { /* fix URI: set explicit control-port */ } else throw e; }","preventionTips":["Never use port 0 in an explicit control address on subscriptions","Centralize channel URI construction in a builder that validates control endpoints","Distinguish publication URIs (dynamic control port OK) from subscription URIs"],"tags":["aeron","udp-channel","configuration","validation"],"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-19T12:17:13.211Z"}