aeron-io/aeron · error · UnknownHostException

could not resolve control address:

Error message

could not resolve control address: 

What it means

Thrown as an UnknownHostException by UdpChannel.parse when the 'control' URI parameter specifies a hostname that cannot be resolved to an IP address. Mirror of the endpoint check, applied to MDC control addresses.

Solutions

1. Verify the control hostname resolves on the driver host (dig/nslookup)
2. Replace the control hostname with an explicit IP address
3. Add a hosts-file or DNS entry for the control address
4. Check control-mode value: control addresses only apply with control-mode=manual or response

Example fix

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

if (uri.contains("control=")) { String h = extractParam(uri, "control"); InetAddress a = InetAddress.getByName(h); if (a.isUnresolved()) throw new IllegalArgumentException("control host unresolvable"); }

static boolean controlResolvable(String uri) { String h = extractParam(uri, "control"); return h == null || isResolvable(h); }

try { sub = aeron.addSubscription(uri, streamId); } catch (InvalidChannelException e) { throw new ConfigException("control address invalid: " + e.getCause()); }

When it happens

Trigger: Using a channel URI like aeron:udp?control=bad.host.example:40456|control-mode=manual where the control hostname fails DNS resolution.

Common situations: Multicast/manual control-mode setups with mistyped control hosts, containers without DNS access, or control addresses valid only on another host.

Related errors

• could not resolve endpoint 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/e8aed115b605ad77. Report an issue: GitHub.

Appendix: source

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

                    "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()
                .protocolFamily(protocolFamily)
                .isMulticast(false)
                .hasExplicitControl(false)
                .hasMulticastTtl(false)
                .hasTagId(false)

View on GitHub (pinned to 6d60124e15)