{"record":{"id":"45fe61f85aef0cef","repo":"aeron-io/aeron","slug":"unable-to-find-multicast-or-loopback-interface-matching","errorCode":null,"errorMessage":"Unable to find multicast or loopback interface matching criteria: <address>/<subnetPrefix>","messagePattern":"Unable to find multicast or loopback interface matching criteria: <address>/<subnetPrefix>","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"aeron-driver/src/main/java/io/aeron/driver/media/InterfaceSearchAddress.java","lineNumber":87,"sourceCode":"                                            localInterface.getInterfaceAddresses());\n        }\n\n        return new InetSocketAddress(interfaceAddress, address.getPort());\n    }\n\n    private NetworkInterface findInterface() throws SocketException\n    {\n        final NetworkInterface[] filteredInterfaces = filterBySubnet(address.getAddress(), subnetPrefix);\n\n        for (final NetworkInterface networkInterface : filteredInterfaces)\n        {\n            if (networkInterface.isUp() && (networkInterface.supportsMulticast() || networkInterface.isLoopback()))\n            {\n                return networkInterface;\n            }\n        }\n\n        throw new IllegalArgumentException(noMatchingInterfacesError(filteredInterfaces));\n    }\n\n    private String noMatchingInterfacesError(final NetworkInterface[] filteredInterfaces) throws SocketException\n    {\n        final StringBuilder builder = new StringBuilder()\n            .append(\"Unable to find multicast or loopback interface matching criteria: \")\n            .append(address.getAddress())\n            .append('/')\n            .append(subnetPrefix);\n\n        if (filteredInterfaces.length > 0)\n        {\n            builder.append(lineSeparator()).append(\"  Candidates:\");\n\n            for (final NetworkInterface ifc : filteredInterfaces)\n            {\n                builder\n                    .append(lineSeparator())","sourceCodeStart":69,"sourceCodeEnd":105,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-driver/src/main/java/io/aeron/driver/media/InterfaceSearchAddress.java#L69-L105","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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","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)","Loosen or correct the subnet prefix so the local NIC's address actually falls within the criteria","In containers, ensure the container has access to a multicast-capable network or explicitly use the loopback interface"],"exampleFix":"// before\nChannelUri.addParameter(\"endpt\", \"0.0.0.0:40456\");\n// after (explicit loopback for local testing)\nChannelUri.addParameter(\"endpt\", \"localhost:40456\");","handlingStrategy":"validation","validationCode":"NetworkInterface.getByName(\"eth0\") != null && NetworkInterface.getByName(\"eth0\").isUp() && (NetworkInterface.getByName(\"eth0\").supportsMulticast() || NetworkInterface.getByName(\"eth0\").isLoopback())\n// or enumerate candidates:\nfor (NetworkInterface nif : java.util.Collections.list(NetworkInterface.getNetworkInterfaces())) {\n    if (nif.isUp() && (nif.supportsMulticast() || nif.isLoopback())) { /* usable candidate */ }\n}","typeGuard":"static boolean isUsableInterface(NetworkInterface nif) throws SocketException {\n    return nif != null && nif.isUp() && (nif.supportsMulticast() || nif.isLoopback());\n}","tryCatchPattern":"try {\n    InterfaceSearchAddress.findInterface(lookupConfig);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().startsWith(\"Unable to find multicast or loopback interface\")) {\n        // log config + enumerate usable NICs, fail fast or fall back to loopback\n    } else { throw e; }\n}","preventionTips":["Enumerate NetworkInterface.getNetworkInterfaces() at startup and log candidates","Prefer IP-address-based config over interface names in multi-host deployments","Test driver config in the same environment type (container/VM) it will run in","For local testing, explicitly use the loopback interface"],"tags":["network","aeron","multicast","interface-resolution"],"backgroundTag":"invalid-argument-value","analyzedSha":"6d60124e15e35c11b49ba2e3c2c2858a09a18803","analyzedAt":"2026-09-12T11:17:07.683Z","contentChangedAt":"2026-09-12T11:17:07.683Z","schemaVersion":2},"datasetVersion":"2026-09-19T12:17:13.211Z"}