{"record":{"id":"b75534328c6e732d","repo":"aeron-io/aeron","slug":"unresolved-endpoint-name-resolver","errorCode":null,"errorMessage":"unresolved - endpoint=, name-resolver=","messagePattern":"unresolved - endpoint=, name-resolver=","errorType":"exception","errorClass":"UnknownHostException","httpStatus":null,"severity":"error","filePath":"aeron-driver/src/main/java/io/aeron/driver/media/UdpChannel.java","lineNumber":1033,"sourceCode":"            return UnresolvedInterface.parse(interfaceValue);\n        }\n\n        return InterfaceSearchAddress.wildcard();\n    }\n\n    private static InetSocketAddress getEndpointAddress(final ChannelUri uri, final NameResolver nameResolver)\n        throws UnknownHostException\n    {\n        InetSocketAddress address = null;\n        final String endpointValue = uri.get(ENDPOINT_PARAM_NAME);\n        if (null != endpointValue)\n        {\n            address = SocketAddressParser.parse(\n                endpointValue, ENDPOINT_PARAM_NAME, false, nameResolver);\n\n            if (address.isUnresolved())\n            {\n                throw new UnknownHostException(\n                    \"unresolved - \" + ENDPOINT_PARAM_NAME + \"=\" + endpointValue +\n                    \", name-resolver=\" + nameResolver.name());\n            }\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","sourceCodeStart":1015,"sourceCodeEnd":1051,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-driver/src/main/java/io/aeron/driver/media/UdpChannel.java#L1015-L1051","documentation":"Aeron's UdpChannel could not resolve the 'endpoint' URI parameter to an IP address. The configured NameResolver (default: default name resolver using DNS/OS lookup) returned an unresolved address, so an UnknownHostException is thrown and the channel cannot be opened. This guards against starting a transport with a destination that cannot be resolved.","triggerScenarios":"Constructing/attempting to open a UdpChannel whose ChannelUri contains an endpoint=<host:port> parameter where the host name does not resolve, and the nameResolver returns an unresolved InetSocketAddress from SocketAddressParser.parse.","commonSituations":"Typo in the endpoint hostname, DNS outage or misconfigured /etc/resolv.conf, using a name only resolvable by a custom NameResolver while the default resolver is configured, container environments without DNS access, or stale hosts-file entries.","solutions":["Verify the endpoint hostname resolves: run a DNS lookup (e.g. nslookup/ping host) from the same machine.","Replace the hostname with a literal IP address in the endpoint= URI parameter.","Configure a custom NameResolver (e.g. Aeron's Nameservice/dynamic resolver) if names must be resolved via a non-DNS mechanism.","Fix DNS configuration (/etc/resolv.conf, search domains, VPN) in the environment."],"exampleFix":"// before\nAeron.connect(ctx); // channel: aeron:udp?endpoint=media-server.local:40456\n// after\nChannelUri uri = ChannelUri.parse(\"aeron:udp?endpoint=192.168.1.10:40456\");\n// or configure a resolver:\ndriverCtx.nameResolver(new MyServiceDiscoveryResolver());","handlingStrategy":"validation","validationCode":"InetAddress addr = InetAddress.getByName(\"media-server.local\");\nif (addr.isUnreachable(2000)) { /* fail fast before opening channel */ }","typeGuard":null,"tryCatchPattern":"try {\n    UdpChannel.parse(channelUri);\n} catch (UnknownHostException e) {\n    logger.error(\"endpoint unresolvable: {}\", e.getMessage());\n    // fall back to IP literal or retry with backoff\n}","preventionTips":["Prefer literal IPs in production channel URIs","Monitor DNS health on driver hosts","Pin custom NameResolver config in driver context","Add startup smoke test that parses all configured channels"],"tags":["network","dns","name-resolution","udp","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"}