{"record":{"id":"f0839dc8ca6a32cf","repo":"aeron-io/aeron","slug":"unresolved-control-name-resolver","errorCode":null,"errorMessage":"unresolved - control=, name-resolver=","messagePattern":"unresolved - control=, name-resolver=","errorType":"exception","errorClass":"UnknownHostException","httpStatus":null,"severity":"error","filePath":"aeron-driver/src/main/java/io/aeron/driver/media/UdpChannel.java","lineNumber":1054,"sourceCode":"            }\n        }\n\n        return address;\n    }\n\n    private static InetSocketAddress getExplicitControlAddress(final ChannelUri uri, final NameResolver nameResolver)\n        throws UnknownHostException\n    {\n        InetSocketAddress address = null;\n        final String controlValue = uri.get(MDC_CONTROL_PARAM_NAME);\n        if (null != controlValue)\n        {\n            address = SocketAddressParser.parse(\n                controlValue, MDC_CONTROL_PARAM_NAME, false, nameResolver);\n\n            if (address.isUnresolved())\n            {\n                throw new UnknownHostException(\n                    \"unresolved - \" + MDC_CONTROL_PARAM_NAME + \"=\" + controlValue +\n                    \", name-resolver=\" + nameResolver.getClass().getName());\n            }\n        }\n\n        return address;\n    }\n\n    private static void validateDataAddress(final byte[] addressAsBytes)\n    {\n        if (BitUtil.isEven(addressAsBytes[addressAsBytes.length - 1]))\n        {\n            throw new IllegalArgumentException(\"multicast data address must be odd\");\n        }\n    }\n\n    private static void validateConfiguration(final ChannelUri uri)\n    {","sourceCodeStart":1036,"sourceCodeEnd":1072,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-driver/src/main/java/io/aeron/driver/media/UdpChannel.java#L1036-L1072","documentation":"Aeron's UdpChannel could not resolve the 'control' URI parameter used for multicast (MDC) channels. The NameResolver produced an unresolved InetSocketAddress for the control address, so an UnknownHostException is thrown and the channel setup fails.","triggerScenarios":"Opening a UdpChannel with a control=<host:port> parameter where the host does not resolve via the configured nameResolver; SocketAddressParser.parse returns an unresolved address and UdpChannel throws UnknownHostException.","commonSituations":"MDC control endpoint hostname typo, DNS unavailable in the deployment environment, custom name resolution service down, or a control address configured with a name only known to a different resolver.","solutions":["Check that the control hostname resolves from the driver host.","Use a literal IP:port for the control= parameter.","Configure/repair the NameResolver used by the media driver.","Fix environment DNS settings (resolv.conf, DNS server reachability)."],"exampleFix":"// before\n\"aeron:udp?control=control-host:40456|control-mode=manual\"\n// after\n\"aeron:udp?control=10.0.0.5:40456|control-mode=manual\"","handlingStrategy":"validation","validationCode":"String control = uri.get(\"control\");\nif (control != null) {\n    String host = control.substring(0, control.indexOf(':'));\n    if (InetAddress.getAllByName(host).length == 0) throw new IllegalArgumentException(\"control unresolvable\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    UdpChannel.parse(channelUri);\n} catch (UnknownHostException e) {\n    logger.error(\"MDC control address unresolvable: {}\", e.getMessage());\n}","preventionTips":["Use IP literals for MDC control addresses","Ensure control and data use the same resolvable naming scheme","Test name resolution in the deployment environment"],"tags":["network","dns","name-resolution","multicast","configuration"],"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-15T23:17:13.987Z"}