aeron-io/aeron · error · IllegalStateException

failed to find / in

Error message

failed to find <address>/<subnetPrefix> in <interfaceAddresses>

What it means

InterfaceSearchAddress.resolve() with wildcard=false resolves a configured name/IP + subnet prefix to the concrete address of a local network interface. resolveToAddressOfInterface throws IllegalStateException when findAddressOnInterface cannot find an address matching the configured address/subnetPrefix among the interface's addresses, meaning the configured endpoint does not match any address actually bound to that interface.

Solutions

1. Verify the interface's actual addresses with ip addr show and align the configured address/subnetPrefix with one of them.
2. Use the interface's own IP with a prefix that matches, or use wildcard form (e.g. 0.0.0.0/0 or just the port) to match any interface.
3. Fix the interface name in the endpoint configuration (eth0 vs ens5 vs enp0s3 naming differences).
4. If addresses are dynamic, configure by interface name with a broader subnet, or resolve dynamically at startup.
5. Use InterfaceLookupAddress/resolve inside try-catch of IllegalStateException and fall back to a default interface in code that builds channels programmatically.

Example fix

// before
.aeronudp("aeron:udp?interface=eth0/24|endpoint=10.0.5.1:40456") // eth0 has no /24 match
// after (verified against `ip addr show eth0` -> 10.0.5.7/24)
.aeronudp("aeron:udp?interface=eth0/24|endpoint=10.0.5.7:40456")

import java.net.*;
import java.util.*;
boolean interfaceMatches(String ifaceName, InetAddress addr, int prefix) throws SocketException {
    NetworkInterface nif = NetworkInterface.getByName(ifaceName);
    if (nif == null) return false;
    for (InterfaceAddress ia : nif.getInterfaceAddresses()) {
        if (ia.getAddress().equals(addr)) return true;
    }
    return false;
}

try {
    resolved = InterfaceSearchAddress.resolve(nameOrIp, port, subnetPrefix, false, interfaceLookup);
} catch (IllegalStateException e) {
    // fall back to wildcard or log the interface's actual addresses
    resolved = InterfaceSearchAddress.resolve("0.0.0.0", port, 0, true, interfaceLookup);
}

When it happens

Trigger: Configuring aeron udp endpoint/control-mode with a named interface or specific IP + subnet prefix (e.g. eth0/24 or 192.168.1.10/24) where the named interface has no address within the given subnet, the IP is not assigned to the interface, or the interface name resolves to a different device than expected.

Common situations: Hostname resolving to an address on a different interface; configuration copied from another machine with different NIC layout; subnet prefix typo (e.g. /24 where the interface uses /16 addressing semantics for matching); DHCP-leased address changed after reboot; container environments where interface names/addresses differ from host.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• ControlSession.RESPONSE_NOT_CONNECTED_MSG + ": " + session
• unknown interface
• no addresses found on interface
• interface is null or empty
• name + " cannot be negative: value=" + value

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

Appendix: source

Thrown at aeron-driver/src/main/java/io/aeron/driver/media/InterfaceSearchAddress.java:68

            localInterface = null;
            resolvedAddress = address;
        }
        else
        {
            localInterface = findInterface();
            resolvedAddress = resolveToAddressOfInterface(localInterface);
        }

        return new ResolvedInterface(localInterface, resolvedAddress);
    }

    private InetSocketAddress resolveToAddressOfInterface(final NetworkInterface localInterface)
    {
        final InetAddress interfaceAddress = findAddressOnInterface(localInterface, address.getAddress(), subnetPrefix);

        if (null == interfaceAddress)
        {
            throw new IllegalStateException("failed to find " + address.getAddress() + "/" + subnetPrefix + " in " +
                                            localInterface.getInterfaceAddresses());
        }

        return new InetSocketAddress(interfaceAddress, address.getPort());
    }

    private NetworkInterface findInterface() throws SocketException
    {
        final NetworkInterface[] filteredInterfaces = filterBySubnet(address.getAddress(), subnetPrefix);

        for (final NetworkInterface networkInterface : filteredInterfaces)
        {
            if (networkInterface.isUp() && (networkInterface.supportsMulticast() || networkInterface.isLoopback()))
            {
                return networkInterface;
            }
        }

View on GitHub (pinned to 6d60124e15)