aeron-io/aeron · error · IllegalArgumentException

interface is null or empty

Error message

interface is null or empty

What it means

UnresolvedInterface.parse was given a null or empty string for a network interface specification and throws IllegalArgumentException. An interface value is required to select the local network interface for a UDP channel, so empty input is rejected immediately.

Solutions

1. Provide a valid interface value in the channel URI, e.g. interface=eth0 or interface=192.168.1.5.
2. Check that the config source (env var, properties) actually supplies a non-empty interface string.
3. Validate the interface value before building the ChannelUri.

Example fix

// before
String iface = System.getProperty("aeron.interface"); // null/empty
UnresolvedInterface.parse(iface);
// after
String iface = System.getProperty("aeron.interface", "eth0");
if (!iface.isEmpty()) { UnresolvedInterface.parse(iface); }

String iface = config.get("interface");
if (iface == null || iface.trim().isEmpty()) {
    throw new IllegalArgumentException("interface must be set (e.g. eth0 or 192.168.1.5)");
}

boolean validInterface(String s) {
    return s != null && !s.trim().isEmpty();
}

try {
    UnresolvedInterface.parse(str);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("null or empty")) { /* supply default interface */ }
}

When it happens

Trigger: Calling UnresolvedInterface.parse(null) or parse("") directly, or configuring a channel URI whose interface= parameter is empty so an empty string reaches parse.

Common situations: Template/config files with an unfilled interface variable, environment variables not set, programmatic channel construction concatenating an empty interface value, or YAML/properties parsing yielding empty strings.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• unknown interface
• no addresses found on interface
• multicast data address must be odd
• invalid fileIoMaxLength=
• segment file length not a power of 2

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

Appendix: source

Thrown at aeron-driver/src/main/java/io/aeron/driver/media/UnresolvedInterface.java:35

import org.agrona.Strings;

import java.net.ProtocolFamily;
import java.net.SocketException;
import java.net.UnknownHostException;

/**
 * Interface specification as found, for example, in the {@code interface=} channel parameter.
 */
sealed interface UnresolvedInterface permits InterfaceSearchAddress, NamedInterface
{
    ResolvedInterface resolve(boolean multicast, ProtocolFamily protocolFamily) throws SocketException;

    static UnresolvedInterface parse(final String str) throws UnknownHostException
    {
        if (Strings.isEmpty(str))
        {
            throw new IllegalArgumentException("interface is null or empty");
        }

        if (str.charAt(0) == NamedInterface.OPENING_CHAR)
        {
            return NamedInterface.parse(str);
        }
        else
        {
            return InterfaceSearchAddress.parse(str);
        }
    }
}

View on GitHub (pinned to 6d60124e15)