{"record":{"id":"1f8f28db1081fa1f","repo":"aeron-io/aeron","slug":"unknown-interface-name","errorCode":null,"errorMessage":"unknown interface <name>","messagePattern":"unknown interface <name>","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"aeron-driver/src/main/java/io/aeron/driver/media/NamedInterface.java","lineNumber":39,"sourceCode":"import java.net.InetSocketAddress;\nimport java.net.InterfaceAddress;\nimport java.net.NetworkInterface;\nimport java.net.ProtocolFamily;\nimport java.net.SocketException;\n\nimport static io.aeron.driver.media.NetworkUtil.getProtocolFamily;\n\nrecord NamedInterface(String name, int port) implements UnresolvedInterface\n{\n    static final char OPENING_CHAR = '{';\n\n    public ResolvedInterface resolve(final boolean multicast, final ProtocolFamily protocolFamily)\n        throws SocketException\n    {\n        final NetworkInterface localInterface = NetworkInterface.getByName(name);\n        if (null == localInterface)\n        {\n            throw new IllegalArgumentException(\"unknown interface \" + name);\n        }\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","sourceCodeStart":21,"sourceCodeEnd":57,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-driver/src/main/java/io/aeron/driver/media/NamedInterface.java#L21-L57","documentation":"Thrown by NamedInterface.resolve when NetworkInterface.getByName(name) returns null, i.e. no network interface with the configured name exists on the host. Aeron requires a concrete NIC to bind to and cannot proceed. The name typically comes from driver configuration or a channel URI.","triggerScenarios":"Configuring an interface by name (e.g. 'eth0', 'en0', 'lo') that does not exist on the machine running the driver; using a name valid on a developer machine but not on the deployment host.","commonSituations":"Docker/Kubernetes where the interface is named differently (e.g. 'eth0' vs 'ens5' or 'lo'); renaming interfaces after reboot (predictable network interface names on Linux); running a config built for macOS on Linux or vice versa.","solutions":["List available interfaces with 'ip link' / 'ifconfig' and correct the configured name to match the host","Prefer configuring by IP address instead of interface name to be more portable across hosts","In containers, verify the interface exists inside the container namespace, not just on the host","Ensure the interface is not renamed by systemd's predictable naming; pin it or update config"],"exampleFix":"// before\n-Daeron.interface=eth0\n// after (verify with: ip link)\n-Daeron.interface=ens5","handlingStrategy":"validation","validationCode":"try {\n    NetworkInterface nif = NetworkInterface.getByName(cfgName);\n    if (nif == null) {\n        java.util.Collections.list(NetworkInterface.getNetworkInterfaces()).forEach(n -> System.out.println(n.getName()));\n        throw new IllegalArgumentException(\"interface '\" + cfgName + \"' not found; see list above\");\n    }\n} catch (SocketException se) { throw new IllegalStateException(se); }","typeGuard":"static boolean interfaceExists(String name) throws SocketException {\n    return NetworkInterface.getByName(name) != null;\n}","tryCatchPattern":"try {\n    namedInterface.resolve(multicast, protocolFamily);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().startsWith(\"unknown interface \")) {\n        // log available interfaces and abort with actionable message\n    } else { throw e; }\n}","preventionTips":["Validate configured interface names against NetworkInterface.getNetworkInterfaces() at startup","Configure by IP address instead of name for cross-host portability","Account for container namespaces and systemd predictable interface naming in deployments","Keep environment-specific interface names in per-environment config files"],"tags":["network","aeron","interface","configuration"],"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"}