{"record":{"id":"a24c5e89f56532fd","repo":"aeron-io/aeron","slug":"could-not-resolve-endpoint-address","errorCode":null,"errorMessage":"could not resolve endpoint address: ","messagePattern":"could not resolve endpoint address: ","errorType":"exception","errorClass":"UnknownHostException","httpStatus":null,"severity":"error","filePath":"aeron-driver/src/main/java/io/aeron/driver/media/UdpChannel.java","lineNumber":182,"sourceCode":"                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;\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()","sourceCodeStart":164,"sourceCodeEnd":200,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-driver/src/main/java/io/aeron/driver/media/UdpChannel.java#L164-L200","documentation":"Thrown as an UnknownHostException by UdpChannel.parse when the 'endpoint' URI parameter contains a hostname that DNS (or the configured NameResolver) cannot resolve to an IP address. Aeron requires all channel addresses to be resolvable before a transport is created.","triggerScenarios":"Passing a channel URI like aeron:udp?endpoint=bad.host.example:40456 where DNS lookup fails, or an endpoint whose name only resolves on a different machine than the driver.","commonSituations":"Typo in hostname, missing DNS entry or /etc/hosts record, driver running in a container/network without access to the DNS zone, or stale DNS after infrastructure changes.","solutions":["Fix or verify the hostname in the endpoint parameter (nslookup/dig it on the driver host)","Use an explicit IP address instead of a hostname in the endpoint URI","Add the hostname to /etc/hosts or configure the Aeron name resolver correctly","Ensure the driver's environment has working DNS resolution"],"exampleFix":"// before\nAeron.connect().addPublication(\"aeron:udp?endpoint=broker.internal:40456\", 1001);\n// after\nAeron.connect().addPublication(\"aeron:udp?endpoint=10.0.1.5:40456\", 1001);","handlingStrategy":"validation","validationCode":"InetAddress addr = InetAddress.getByName(host);\nif (addr.isUnresolved()) throw new IllegalArgumentException(\"endpoint host unresolvable: \" + host);","typeGuard":"static boolean isResolvable(String host) { try { return !InetAddress.getByName(host).isUnresolved(); } catch (UnknownHostException e) { return false; } }","tryCatchPattern":"try { channel = aeron.addPublication(uri, streamId); } catch (InvalidChannelException e) { log.error(\"channel {} invalid: {}\", uri, e.getCause()); }","preventionTips":["Prefer literal IPs in channel URIs for production","Verify hostnames resolve on the driver host, not the client","Keep /etc/hosts or DNS entries in sync with service discovery","Add channel URI validation before handing URIs to the Aeron client"],"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"}