aeron-io/aeron · error · UnknownHostException

unresolved - control=, name-resolver=

Error message

unresolved - control=, name-resolver=

What it means

Aeron's UdpChannel could not resolve the 'control' URI parameter used for multicast (MDC) channels. The NameResolver produced an unresolved InetSocketAddress for the control address, so an UnknownHostException is thrown and the channel setup fails.

Solutions

1. Check that the control hostname resolves from the driver host.
2. Use a literal IP:port for the control= parameter.
3. Configure/repair the NameResolver used by the media driver.
4. Fix environment DNS settings (resolv.conf, DNS server reachability).

Example fix

// before
"aeron:udp?control=control-host:40456|control-mode=manual"
// after
"aeron:udp?control=10.0.0.5:40456|control-mode=manual"

String control = uri.get("control");
if (control != null) {
    String host = control.substring(0, control.indexOf(':'));
    if (InetAddress.getAllByName(host).length == 0) throw new IllegalArgumentException("control unresolvable");
}

try {
    UdpChannel.parse(channelUri);
} catch (UnknownHostException e) {
    logger.error("MDC control address unresolvable: {}", e.getMessage());
}

When it happens

Trigger: Opening a UdpChannel with a control=<host:port> parameter where the host does not resolve via the configured nameResolver; SocketAddressParser.parse returns an unresolved address and UdpChannel throws UnknownHostException.

Common situations: MDC control endpoint hostname typo, DNS unavailable in the deployment environment, custom name resolution service down, or a control address configured with a name only known to a different resolver.

Related errors

• unresolved - endpoint=, name-resolver=
• multicast data address must be odd
• re-resolve endpoint channel error -
• unresolved - endpoint=, name-resolver=
• unsupported multicast flow control strategy: fc=

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

Appendix: source

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

            }
        }

        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);

            if (address.isUnresolved())
            {
                throw new UnknownHostException(
                    "unresolved - " + MDC_CONTROL_PARAM_NAME + "=" + controlValue +
                    ", name-resolver=" + nameResolver.getClass().getName());
            }
        }

        return address;
    }

    private static void validateDataAddress(final byte[] addressAsBytes)
    {
        if (BitUtil.isEven(addressAsBytes[addressAsBytes.length - 1]))
        {
            throw new IllegalArgumentException("multicast data address must be odd");
        }
    }

    private static void validateConfiguration(final ChannelUri uri)
    {

View on GitHub (pinned to 6d60124e15)