aeron-io/aeron · error · IllegalArgumentException

Unable to find multicast or loopback interface matching…

Error message

Unable to find multicast or loopback interface matching criteria: <address>/<subnetPrefix>

What it means

Thrown when Aeron's media driver cannot find a local network interface that is both up and either multicast-capable or loopback while resolving an InterfaceSearchAddress. It means the address/subnet criteria in the driver configuration matched no usable NIC. The library throws IllegalArgumentException to abort startup rather than bind to an arbitrary interface.

Solutions

1. Verify the interface specified in the driver config (e.g. aeron.interface=... or destination URLs) exists on the host: run 'ip addr' / 'ifconfig' and correct the address or name
2. Check the interface is UP and supports multicast (or use the loopback interface for local testing, e.g. use 127.0.0.1 with lo)
3. Loosen or correct the subnet prefix so the local NIC's address actually falls within the criteria
4. In containers, ensure the container has access to a multicast-capable network or explicitly use the loopback interface

Example fix

// before
ChannelUri.addParameter("endpt", "0.0.0.0:40456");
// after (explicit loopback for local testing)
ChannelUri.addParameter("endpt", "localhost:40456");

NetworkInterface.getByName("eth0") != null && NetworkInterface.getByName("eth0").isUp() && (NetworkInterface.getByName("eth0").supportsMulticast() || NetworkInterface.getByName("eth0").isLoopback())
// or enumerate candidates:
for (NetworkInterface nif : java.util.Collections.list(NetworkInterface.getNetworkInterfaces())) {
    if (nif.isUp() && (nif.supportsMulticast() || nif.isLoopback())) { /* usable candidate */ }
}

static boolean isUsableInterface(NetworkInterface nif) throws SocketException {
    return nif != null && nif.isUp() && (nif.supportsMulticast() || nif.isLoopback());
}

try {
    InterfaceSearchAddress.findInterface(lookupConfig);
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("Unable to find multicast or loopback interface")) {
        // log config + enumerate usable NICs, fail fast or fall back to loopback
    } else { throw e; }
}

When it happens

Trigger: Calling InterfaceSearchAddress.findInterface (via resolve) with a search address whose subnet prefix / wildcard criteria exclude every local NIC, or when all matching interfaces are down or lack multicast/loopback capability.

Common situations: Running the media driver in a container or VM with no multicast-capable interface; specifying an interface name/IP that does not exist on the host; typo in AERON_DRIVER config aeron.interface or aeron.mtu.* settings; VPN or downed NIC filtering out candidates.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• could not re-resolve: control=
• could not re-resolve: endpoint=
• could not resolve control address:
• could not resolve endpoint address:
• failed to fetch remote recording descriptor

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

Appendix: source

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

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

        throw new IllegalArgumentException(noMatchingInterfacesError(filteredInterfaces));
    }

    private String noMatchingInterfacesError(final NetworkInterface[] filteredInterfaces) throws SocketException
    {
        final StringBuilder builder = new StringBuilder()
            .append("Unable to find multicast or loopback interface matching criteria: ")
            .append(address.getAddress())
            .append('/')
            .append(subnetPrefix);

        if (filteredInterfaces.length > 0)
        {
            builder.append(lineSeparator()).append("  Candidates:");

            for (final NetworkInterface ifc : filteredInterfaces)
            {
                builder
                    .append(lineSeparator())

View on GitHub (pinned to 6d60124e15)