aeron-io/aeron · error · IllegalArgumentException

unknown interface

Error message

unknown interface <name>

What it means

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.

Solutions

1. List available interfaces with 'ip link' / 'ifconfig' and correct the configured name to match the host
2. Prefer configuring by IP address instead of interface name to be more portable across hosts
3. In containers, verify the interface exists inside the container namespace, not just on the host
4. Ensure the interface is not renamed by systemd's predictable naming; pin it or update config

Example fix

// before
-Daeron.interface=eth0
// after (verify with: ip link)
-Daeron.interface=ens5

try {
    NetworkInterface nif = NetworkInterface.getByName(cfgName);
    if (nif == null) {
        java.util.Collections.list(NetworkInterface.getNetworkInterfaces()).forEach(n -> System.out.println(n.getName()));
        throw new IllegalArgumentException("interface '" + cfgName + "' not found; see list above");
    }
} catch (SocketException se) { throw new IllegalStateException(se); }

static boolean interfaceExists(String name) throws SocketException {
    return NetworkInterface.getByName(name) != null;
}

try {
    namedInterface.resolve(multicast, protocolFamily);
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("unknown interface ")) {
        // log available interfaces and abort with actionable message
    } else { throw e; }
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• no addresses found on interface
• interface is null or empty
• Aeron client instance must set…
• Aeron client must use a RethrowingErrorHandler
• segment file length not a power of 2

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

Appendix: source

Thrown at aeron-driver/src/main/java/io/aeron/driver/media/NamedInterface.java:39

import java.net.InetSocketAddress;
import java.net.InterfaceAddress;
import java.net.NetworkInterface;
import java.net.ProtocolFamily;
import java.net.SocketException;

import static io.aeron.driver.media.NetworkUtil.getProtocolFamily;

record NamedInterface(String name, int port) implements UnresolvedInterface
{
    static final char OPENING_CHAR = '{';

    public ResolvedInterface resolve(final boolean multicast, final ProtocolFamily protocolFamily)
        throws SocketException
    {
        final NetworkInterface localInterface = NetworkInterface.getByName(name);
        if (null == localInterface)
        {
            throw new IllegalArgumentException("unknown interface " + name);
        }
        final InetSocketAddress address = resolveToFirstAddressOfFamily(localInterface, protocolFamily);
        return new ResolvedInterface(localInterface, address);
    }

    private InetSocketAddress resolveToFirstAddressOfFamily(
        final NetworkInterface localInterface,
        final ProtocolFamily protocolFamily)
    {
        for (final InterfaceAddress interfaceAddress : localInterface.getInterfaceAddresses())
        {
            final InetAddress address = interfaceAddress.getAddress();
            if (getProtocolFamily(address) == protocolFamily)
            {
                return new InetSocketAddress(address, port);
            }
        }

View on GitHub (pinned to 6d60124e15)