aeron-io/aeron · error · UnknownHostException

could not resolve endpoint address:

Error message

could not resolve endpoint address: 

What it means

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.

Solutions

1. Fix or verify the hostname in the endpoint parameter (nslookup/dig it on the driver host)
2. Use an explicit IP address instead of a hostname in the endpoint URI
3. Add the hostname to /etc/hosts or configure the Aeron name resolver correctly
4. Ensure the driver's environment has working DNS resolution

Example fix

// before
Aeron.connect().addPublication("aeron:udp?endpoint=broker.internal:40456", 1001);
// after
Aeron.connect().addPublication("aeron:udp?endpoint=10.0.1.5:40456", 1001);

InetAddress addr = InetAddress.getByName(host);
if (addr.isUnresolved()) throw new IllegalArgumentException("endpoint host unresolvable: " + host);

static boolean isResolvable(String host) { try { return !InetAddress.getByName(host).isUnresolved(); } catch (UnknownHostException e) { return false; } }

try { channel = aeron.addPublication(uri, streamId); } catch (InvalidChannelException e) { log.error("channel {} invalid: {}", uri, e.getCause()); }

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• could not resolve control address:
• could not re-resolve: control=
• could not re-resolve: endpoint=
• unresolved - endpoint=, name-resolver=
• re-resolve endpoint channel error -

AI-assisted analysis of aeron-io/aeron@6d60124e15 (2026-09-12). Data as JSON: /api/errors/a24c5e89f56532fd. Report an issue: GitHub.

Appendix: source

Thrown at aeron-driver/src/main/java/io/aeron/driver/media/UdpChannel.java:182

                null == endpointAddress && null == controlAddress && null == tagIdStr;

            if (ControlMode.DYNAMIC == controlMode && null == controlAddress)
            {
                throw new IllegalArgumentException(
                    "explicit control expected with dynamic control mode: " + channelUriString);
            }

            if (hasNoDistinguishingCharacteristic && ControlMode.MANUAL != controlMode &&
                ControlMode.RESPONSE != controlMode)
            {
                throw new IllegalArgumentException(
                    "URIs for UDP must specify an endpoint, control, tags, or control-mode=manual/response: " +
                    channelUriString);
            }

            if (null != endpointAddress && endpointAddress.isUnresolved())
            {
                throw new UnknownHostException("could not resolve endpoint address: " + endpointAddress);
            }

            if (null != controlAddress && controlAddress.isUnresolved())
            {
                throw new UnknownHostException("could not resolve control address: " + controlAddress);
            }

            boolean hasExplicitEndpoint = true;
            if (null == endpointAddress)
            {
                hasExplicitEndpoint = false;
                endpointAddress = null != controlAddress && controlAddress.getAddress() instanceof Inet6Address ?
                    ANY_IPV6 : ANY_IPV4;
            }

            final ProtocolFamily protocolFamily = getProtocolFamily(endpointAddress.getAddress());

            final Context context = new Context()

View on GitHub (pinned to 6d60124e15)