aeron-io/aeron · error · UnknownHostException

unresolved - endpoint=, name-resolver=

Error message

unresolved - endpoint=, name-resolver=

What it means

UdpNameResolutionTransport.getInetSocketAddress could not resolve the endpoint host:port for a name-resolution-driven transport. SocketAddressParser.parse produced an unresolved InetSocketAddress and an UnknownHostException naming the endpoint value and resolver is thrown.

Solutions

1. Verify the name resolution service is running and contains the requested endpoint name.
2. Check the endpoint string for typos or unsupported formats.
3. Use a literal IP if dynamic resolution is unnecessary.
4. Retry after ensuring the peer has registered its address with the resolver.

Example fix

// before
"aeron:udp?endpoint=peer-3.cluster.internal:20111" // name not registered
// after
// register peer-3.cluster.internal in the name service, or use:
"aeron:udp?endpoint=10.1.2.3:20111"

if (hostAndPort == null || hostAndPort.isEmpty()) throw new IllegalArgumentException("endpoint required");
InetAddress a = InetAddress.getByName(hostPart(hostAndPort));
if (a.isAnyLocalAddress() && !allowWildcard) throw new IllegalArgumentException("unresolvable");

try {
    InetSocketAddress addr = transport.getInetSocketAddress();
} catch (UnknownHostException e) {
    logger.warn("name not yet registered: {}", e.getMessage());
    // retry after resolver catches up
}

When it happens

Trigger: A transport that resolves its endpoint dynamically (UdpNameResolutionTransport) receives a host name the configured NameResolver cannot resolve; getInetSocketAddress detects address.isUnresolved() and throws.

Common situations: Name-service (e.g. Aeron name resolution service) not running or unreachable, hostname absent from the discovery service, DNS misconfiguration in containers, or race where the peer has not yet registered its address.

Related errors

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

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

Appendix: source

Thrown at aeron-driver/src/main/java/io/aeron/driver/media/UdpNameResolutionTransport.java:186

    /**
     * Get the {@link InetSocketAddress} for a host and port endpoint using the default name resolver.
     *
     * @param hostAndPort  to parse.
     * @param nameResolver to resolve a name to an {@link InetAddress}.
     * @return the resolved {@link InetSocketAddress} if successful or null if not.
     */
    public static InetSocketAddress getInetSocketAddress(final String hostAndPort, final NameResolver nameResolver)
    {
        InetSocketAddress address = null;

        try
        {
            address = SocketAddressParser.parse(
                hostAndPort, CommonContext.ENDPOINT_PARAM_NAME, false, nameResolver);

            if (address.isUnresolved())
            {
                throw new UnknownHostException(
                    "unresolved - " + CommonContext.ENDPOINT_PARAM_NAME + "=" + hostAndPort +
                    ", name-resolver=" + nameResolver.getClass().getName());
            }
        }
        catch (final UnknownHostException ex)
        {
            LangUtil.rethrowUnchecked(ex);
        }

        return address;
    }
}

View on GitHub (pinned to 6d60124e15)