aeron-io/aeron · error · UnknownHostException

unresolved - endpoint=, name-resolver=

Error message

unresolved - endpoint=, name-resolver=

What it means

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.

Solutions

1. Verify the endpoint hostname resolves: run a DNS lookup (e.g. nslookup/ping host) from the same machine.
2. Replace the hostname with a literal IP address in the endpoint= URI parameter.
3. Configure a custom NameResolver (e.g. Aeron's Nameservice/dynamic resolver) if names must be resolved via a non-DNS mechanism.
4. Fix DNS configuration (/etc/resolv.conf, search domains, VPN) in the environment.

Example fix

// before
Aeron.connect(ctx); // channel: aeron:udp?endpoint=media-server.local:40456
// after
ChannelUri uri = ChannelUri.parse("aeron:udp?endpoint=192.168.1.10:40456");
// or configure a resolver:
driverCtx.nameResolver(new MyServiceDiscoveryResolver());

InetAddress addr = InetAddress.getByName("media-server.local");
if (addr.isUnreachable(2000)) { /* fail fast before opening channel */ }

try {
    UdpChannel.parse(channelUri);
} catch (UnknownHostException e) {
    logger.error("endpoint unresolvable: {}", e.getMessage());
    // fall back to IP literal or retry with backoff
}

When it happens

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

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

Related errors

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

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

Appendix: source

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

            return UnresolvedInterface.parse(interfaceValue);
        }

        return InterfaceSearchAddress.wildcard();
    }

    private static InetSocketAddress getEndpointAddress(final ChannelUri uri, final NameResolver nameResolver)
        throws UnknownHostException
    {
        InetSocketAddress address = null;
        final String endpointValue = uri.get(ENDPOINT_PARAM_NAME);
        if (null != endpointValue)
        {
            address = SocketAddressParser.parse(
                endpointValue, ENDPOINT_PARAM_NAME, false, nameResolver);

            if (address.isUnresolved())
            {
                throw new UnknownHostException(
                    "unresolved - " + ENDPOINT_PARAM_NAME + "=" + endpointValue +
                    ", name-resolver=" + nameResolver.name());
            }
        }

        return address;
    }

    private static InetSocketAddress getExplicitControlAddress(final ChannelUri uri, final NameResolver nameResolver)
        throws UnknownHostException
    {
        InetSocketAddress address = null;
        final String controlValue = uri.get(MDC_CONTROL_PARAM_NAME);
        if (null != controlValue)
        {
            address = SocketAddressParser.parse(
                controlValue, MDC_CONTROL_PARAM_NAME, false, nameResolver);

View on GitHub (pinned to 6d60124e15)