aeron-io/aeron · error · IllegalStateException

no addresses found on interface

Error message

no <protocolFamily> addresses found on interface <name>

What it means

Aeron throws this IllegalStateException when resolving a named network interface to the first local address matching the requested protocol family (IPv4 or IPv6). It means the interface exists but has no address of that family, so a valid InetSocketAddress cannot be constructed. This prevents the driver from binding/subscribing on an interface that cannot support the requested address family.

Solutions

1. Check the interface's configured addresses (ip addr show <name>) and confirm it has an address of the protocol family your channel URI requires
2. Correct the channel URI to use an address of the family the interface actually has (e.g. use an IPv6 endpoint like [::1]:40456 instead of 127.0.0.1:40456)
3. Name the interface/address explicitly in the URI with the right family instead of relying on interface-name resolution
4. Enable the missing address family on the interface (e.g. sysctl net.ipv6.conf.eth0.disable_ipv6=0) or add an address of the required family

Example fix

// before
Aeron.connect(new Aeron.Context().aeronDirectoryName(dir)); // channel: aeron:udp?interface=eth0|endpoint=224.0.1.1:40456 on an IPv6-only eth0
// after
// channel: aeron:udp?interface=eth0|endpoint=[ff0e::1:40456] or add an IPv4 address to eth0

NetworkInterface nif = NetworkInterface.getByName("eth0");
boolean hasFamily = nif != null && nif.getInterfaceAddresses().stream()
    .anyMatch(a -> a.getAddress() instanceof Inet4Address); // or Inet6Address
if (!hasFamily) throw new IllegalArgumentException("eth0 lacks required address family");

When it happens

Trigger: Calling resolveToFirstAddressOfFamily (via NamedInterface.address) for e.g. protocolFamily=IPv4 on an interface that only has IPv6 addresses configured (or vice versa), typically when a channel URI names an interface like eth0 or lo and the family mismatches.

Common situations: Dual-stack misconfiguration: URI specifies IPv4 endpoints but the named interface only has IPv6 addresses (or IPv6 disabled via sysctl disable_ipv6); running in containers where the interface lacks the expected family; specifying 'lo' with an IPv6-only bind.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• unknown interface
• interface is null or empty
• failed to find / in
• unresolved - endpoint=, name-resolver=
• unresolved - control=, name-resolver=

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

Appendix: source

Thrown at aeron-driver/src/main/java/io/aeron/driver/media/NamedInterface.java:58

        }
        final InetSocketAddress address = resolveToFirstAddressOfFamily(localInterface, protocolFamily);
        return new ResolvedInterface(localInterface, address);
    }

    private InetSocketAddress resolveToFirstAddressOfFamily(
        final NetworkInterface localInterface,
        final ProtocolFamily protocolFamily)
    {
        for (final InterfaceAddress interfaceAddress : localInterface.getInterfaceAddresses())
        {
            final InetAddress address = interfaceAddress.getAddress();
            if (getProtocolFamily(address) == protocolFamily)
            {
                return new InetSocketAddress(address, port);
            }
        }

        throw new IllegalStateException(
            "no " + protocolFamily + " addresses found on interface " + localInterface.getName());
    }

    static NamedInterface parse(final String str)
    {
        if (Strings.isEmpty(str) || str.charAt(0) != OPENING_CHAR)
        {
            throw parseException(str);
        }

        final int nameEnd = str.lastIndexOf('}');
        if (nameEnd <= 1)
        {
            throw parseException(str);
        }
        final String name = str.substring(1, nameEnd);

        int port = 0;

View on GitHub (pinned to 6d60124e15)