{"record":{"id":"5a19ed12af58757f","repo":"aeron-io/aeron","slug":"uris-for-udp-must-specify-an-endpoint-control-tags-or","errorCode":null,"errorMessage":"URIs for UDP must specify an endpoint, control, tags, or control-mode=manual/response: ","messagePattern":"URIs for UDP must specify an endpoint, control, tags, or control-mode=manual/response: ","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"aeron-driver/src/main/java/io/aeron/driver/media/UdpChannel.java","lineNumber":175,"sourceCode":"\n            final boolean requiresAdditionalSuffix = !isDestination &&\n                (null == endpointAddress && null == controlAddress ||\n                (null != endpointAddress && endpointAddress.getPort() == 0) ||\n                (null != controlAddress && controlAddress.getPort() == 0));\n\n            final boolean hasNoDistinguishingCharacteristic =\n                null == endpointAddress && null == controlAddress && null == tagIdStr;\n\n            if (ControlMode.DYNAMIC == controlMode && null == controlAddress)\n            {\n                throw new IllegalArgumentException(\n                    \"explicit control expected with dynamic control mode: \" + channelUriString);\n            }\n\n            if (hasNoDistinguishingCharacteristic && ControlMode.MANUAL != controlMode &&\n                ControlMode.RESPONSE != controlMode)\n            {\n                throw new IllegalArgumentException(\n                    \"URIs for UDP must specify an endpoint, control, tags, or control-mode=manual/response: \" +\n                    channelUriString);\n            }\n\n            if (null != endpointAddress && endpointAddress.isUnresolved())\n            {\n                throw new UnknownHostException(\"could not resolve endpoint address: \" + endpointAddress);\n            }\n\n            if (null != controlAddress && controlAddress.isUnresolved())\n            {\n                throw new UnknownHostException(\"could not resolve control address: \" + controlAddress);\n            }\n\n            boolean hasExplicitEndpoint = true;\n            if (null == endpointAddress)\n            {\n                hasExplicitEndpoint = false;","sourceCodeStart":157,"sourceCodeEnd":193,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-driver/src/main/java/io/aeron/driver/media/UdpChannel.java#L157-L193","documentation":"UdpChannel.parse throws IllegalArgumentException when a UDP channel URI has no distinguishing characteristic — no endpoint, no control address, and no tags — and the control mode is neither manual nor response. Such a URI gives the driver nothing to bind or connect to, so it is rejected at parse time.","triggerScenarios":"Passing URIs like aeron:udp or aeron:udp?someOtherParam=x (without endpoint=, control=, tags=, or control-mode=manual/response) to Aeron.addPublication/addSubscription or publication/subscription images.","commonSituations":"Building URIs programmatically where all endpoint parameters end up empty; typos in parameter names (endpooint=); copy of the response/manual mode usage where control-mode was removed; incomplete MDC configuration.","solutions":["Add an endpoint to the URI, e.g. aeron:udp?endpoint=127.0.0.1:40456","For MDC, add control-mode=manual (destinations added at runtime) or an explicit control address/tags","For response channels use control-mode=response; verify parameter spelling (endpoint, control, tags) since unknown params are ignored"],"exampleFix":"// before\n\"aeron:udp\"\n// after\n\"aeron:udp?endpoint=127.0.0.1:40456\" // or \"aeron:udp?control-mode=manual\"","handlingStrategy":"validation","validationCode":"boolean hasEndpoint = nonEmpty(params.get(\"endpoint\"));\nboolean hasControl = nonEmpty(params.get(\"control\"));\nboolean hasTags = nonEmpty(params.get(\"tags\"));\nString mode = params.get(\"control-mode\");\nboolean manualOrResponse = \"manual\".equals(mode) || \"response\".equals(mode);\nif (!(hasEndpoint || hasControl || hasTags || manualOrResponse)) {\n    throw new IllegalArgumentException(\"UDP channel needs endpoint, control, tags, or control-mode=manual/response\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    UdpChannel.parse(uri, true, NameResolver.NULL_NAME_RESOLVER);\n} catch (IllegalArgumentException e) {\n    // supply an endpoint or a valid control-mode before retrying\n}","preventionTips":["Never emit bare aeron:udp URIs; require at least one of endpoint/control/tags/control-mode","Validate URI parameter names for typos — unknown names are ignored, producing this error","Use a shared URI builder with compile-time-known parameter names"],"tags":["aeron","uri","configuration","channel"],"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"}