{"record":{"id":"da14815bfc0f9bf4","repo":"aeron-io/aeron","slug":"no-protocolfamily-addresses-found-on-interface-name","errorCode":null,"errorMessage":"no <protocolFamily> addresses found on interface <name>","messagePattern":"no <protocolFamily> addresses found on interface <name>","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"aeron-driver/src/main/java/io/aeron/driver/media/NamedInterface.java","lineNumber":58,"sourceCode":"        }\n        final InetSocketAddress address = resolveToFirstAddressOfFamily(localInterface, protocolFamily);\n        return new ResolvedInterface(localInterface, address);\n    }\n\n    private InetSocketAddress resolveToFirstAddressOfFamily(\n        final NetworkInterface localInterface,\n        final ProtocolFamily protocolFamily)\n    {\n        for (final InterfaceAddress interfaceAddress : localInterface.getInterfaceAddresses())\n        {\n            final InetAddress address = interfaceAddress.getAddress();\n            if (getProtocolFamily(address) == protocolFamily)\n            {\n                return new InetSocketAddress(address, port);\n            }\n        }\n\n        throw new IllegalStateException(\n            \"no \" + protocolFamily + \" addresses found on interface \" + localInterface.getName());\n    }\n\n    static NamedInterface parse(final String str)\n    {\n        if (Strings.isEmpty(str) || str.charAt(0) != OPENING_CHAR)\n        {\n            throw parseException(str);\n        }\n\n        final int nameEnd = str.lastIndexOf('}');\n        if (nameEnd <= 1)\n        {\n            throw parseException(str);\n        }\n        final String name = str.substring(1, nameEnd);\n\n        int port = 0;","sourceCodeStart":40,"sourceCodeEnd":76,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-driver/src/main/java/io/aeron/driver/media/NamedInterface.java#L40-L76","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check the interface's configured addresses (ip addr show <name>) and confirm it has an address of the protocol family your channel URI requires","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)","Name the interface/address explicitly in the URI with the right family instead of relying on interface-name resolution","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"],"exampleFix":"// before\nAeron.connect(new Aeron.Context().aeronDirectoryName(dir)); // channel: aeron:udp?interface=eth0|endpoint=224.0.1.1:40456 on an IPv6-only eth0\n// after\n// channel: aeron:udp?interface=eth0|endpoint=[ff0e::1:40456] or add an IPv4 address to eth0","handlingStrategy":"validation","validationCode":"NetworkInterface nif = NetworkInterface.getByName(\"eth0\");\nboolean hasFamily = nif != null && nif.getInterfaceAddresses().stream()\n    .anyMatch(a -> a.getAddress() instanceof Inet4Address); // or Inet6Address\nif (!hasFamily) throw new IllegalArgumentException(\"eth0 lacks required address family\");","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Inspect interface addresses (ip addr) before configuring channels","Match the URI address family to an address actually present on the interface","In containers, verify the interface inside the container netns, not the host","Prefer explicit IP addresses over interface names when family matters"],"tags":["network","ipv6","interface","configuration"],"backgroundTag":"invalid-config-value","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"}