{"record":{"id":"76e32315f0e6a8db","repo":"aeron-io/aeron","slug":"failed-to-find-address-subnetprefix-in-interfaceaddresses","errorCode":null,"errorMessage":"failed to find <address>/<subnetPrefix> in <interfaceAddresses>","messagePattern":"failed to find <address>/<subnetPrefix> in <interfaceAddresses>","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"aeron-driver/src/main/java/io/aeron/driver/media/InterfaceSearchAddress.java","lineNumber":68,"sourceCode":"            localInterface = null;\n            resolvedAddress = address;\n        }\n        else\n        {\n            localInterface = findInterface();\n            resolvedAddress = resolveToAddressOfInterface(localInterface);\n        }\n\n        return new ResolvedInterface(localInterface, resolvedAddress);\n    }\n\n    private InetSocketAddress resolveToAddressOfInterface(final NetworkInterface localInterface)\n    {\n        final InetAddress interfaceAddress = findAddressOnInterface(localInterface, address.getAddress(), subnetPrefix);\n\n        if (null == interfaceAddress)\n        {\n            throw new IllegalStateException(\"failed to find \" + address.getAddress() + \"/\" + subnetPrefix + \" in \" +\n                                            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","sourceCodeStart":50,"sourceCodeEnd":86,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-driver/src/main/java/io/aeron/driver/media/InterfaceSearchAddress.java#L50-L86","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the interface's actual addresses with ip addr show and align the configured address/subnetPrefix with one of them.","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.","Fix the interface name in the endpoint configuration (eth0 vs ens5 vs enp0s3 naming differences).","If addresses are dynamic, configure by interface name with a broader subnet, or resolve dynamically at startup.","Use InterfaceLookupAddress/resolve inside try-catch of IllegalStateException and fall back to a default interface in code that builds channels programmatically."],"exampleFix":"// before\n.aeronudp(\"aeron:udp?interface=eth0/24|endpoint=10.0.5.1:40456\") // eth0 has no /24 match\n// after (verified against `ip addr show eth0` -> 10.0.5.7/24)\n.aeronudp(\"aeron:udp?interface=eth0/24|endpoint=10.0.5.7:40456\")","handlingStrategy":"validation","validationCode":"import java.net.*;\nimport java.util.*;\nboolean interfaceMatches(String ifaceName, InetAddress addr, int prefix) throws SocketException {\n    NetworkInterface nif = NetworkInterface.getByName(ifaceName);\n    if (nif == null) return false;\n    for (InterfaceAddress ia : nif.getInterfaceAddresses()) {\n        if (ia.getAddress().equals(addr)) return true;\n    }\n    return false;\n}","typeGuard":null,"tryCatchPattern":"try {\n    resolved = InterfaceSearchAddress.resolve(nameOrIp, port, subnetPrefix, false, interfaceLookup);\n} catch (IllegalStateException e) {\n    // fall back to wildcard or log the interface's actual addresses\n    resolved = InterfaceSearchAddress.resolve(\"0.0.0.0\", port, 0, true, interfaceLookup);\n}","preventionTips":["Run `ip addr show` and copy the exact IP/subnet from the target interface into config.","Prefer configuring endpoints by interface name rather than hostnames that may resolve elsewhere.","Account for dynamic (DHCP/container) address changes; re-verify at startup.","Use wildcard interface (true wildcard + prefix 0) when any interface is acceptable."],"tags":["java","network","interface","illegal-state"],"backgroundTag":"resource-not-found","analyzedSha":"6d60124e15e35c11b49ba2e3c2c2858a09a18803","analyzedAt":"2026-09-12T11:17:07.683Z","contentChangedAt":"2026-09-12T11:17:07.683Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}