{"record":{"id":"e8aed115b605ad77","repo":"aeron-io/aeron","slug":"could-not-resolve-control-address","errorCode":null,"errorMessage":"could not resolve control address: ","messagePattern":"could not resolve control address: ","errorType":"exception","errorClass":"UnknownHostException","httpStatus":null,"severity":"error","filePath":"aeron-driver/src/main/java/io/aeron/driver/media/UdpChannel.java","lineNumber":187,"sourceCode":"                    \"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;\n                endpointAddress = null != controlAddress && controlAddress.getAddress() instanceof Inet6Address ?\n                    ANY_IPV6 : ANY_IPV4;\n            }\n\n            final ProtocolFamily protocolFamily = getProtocolFamily(endpointAddress.getAddress());\n\n            final Context context = new Context()\n                .protocolFamily(protocolFamily)\n                .isMulticast(false)\n                .hasExplicitControl(false)\n                .hasMulticastTtl(false)\n                .hasTagId(false)","sourceCodeStart":169,"sourceCodeEnd":205,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-driver/src/main/java/io/aeron/driver/media/UdpChannel.java#L169-L205","documentation":"Thrown as an UnknownHostException by UdpChannel.parse when the 'control' URI parameter specifies a hostname that cannot be resolved to an IP address. Mirror of the endpoint check, applied to MDC control addresses.","triggerScenarios":"Using a channel URI like aeron:udp?control=bad.host.example:40456|control-mode=manual where the control hostname fails DNS resolution.","commonSituations":"Multicast/manual control-mode setups with mistyped control hosts, containers without DNS access, or control addresses valid only on another host.","solutions":["Verify the control hostname resolves on the driver host (dig/nslookup)","Replace the control hostname with an explicit IP address","Add a hosts-file or DNS entry for the control address","Check control-mode value: control addresses only apply with control-mode=manual or response"],"exampleFix":"// before\n\"aeron:udp?control=ctrl.host:40456|control-mode=manual\"\n// after\n\"aeron:udp?control=10.0.1.5:40456|control-mode=manual\"","handlingStrategy":"validation","validationCode":"if (uri.contains(\"control=\")) { String h = extractParam(uri, \"control\"); InetAddress a = InetAddress.getByName(h); if (a.isUnresolved()) throw new IllegalArgumentException(\"control host unresolvable\"); }","typeGuard":"static boolean controlResolvable(String uri) { String h = extractParam(uri, \"control\"); return h == null || isResolvable(h); }","tryCatchPattern":"try { sub = aeron.addSubscription(uri, streamId); } catch (InvalidChannelException e) { throw new ConfigException(\"control address invalid: \" + e.getCause()); }","preventionTips":["Only set control= with control-mode=manual or response","Pin control addresses to IPs in containers","Test MDC URIs on the media driver host before deployment"],"tags":["network","dns","aeron","udp"],"backgroundTag":"dns-resolution-failed","analyzedSha":"6d60124e15e35c11b49ba2e3c2c2858a09a18803","analyzedAt":"2026-09-12T11:17:07.683Z","contentChangedAt":"2026-09-12T11:17:07.683Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}