aeron-io/aeron · error · IllegalArgumentException

search address string is null or empty

Error message

search address string is null or empty

What it means

Thrown by InterfaceSearchAddress.parse when the string supplied to define an interface search address is null or empty. Parse expects a non-empty 'address[:port][/subnet]' spec. It is an immediate input-validation failure before any parsing of delimiters.

Solutions

1. Provide a valid interface search address string such as '127.0.0.1:0' or '192.168.1.1/24'
2. Check the config source (system property, env var, channel URI) actually has a value before passing it to parse
3. Trim whitespace-only strings, which Strings.isEmpty may also flag or which will otherwise fail later parsing

Example fix

// before
String iface = System.getProperty("aeron.interface");
InterfaceSearchAddress.parse(iface);
// after
String iface = System.getProperty("aeron.interface", "127.0.0.1:0");
if (iface != null && !iface.trim().isEmpty()) { InterfaceSearchAddress.parse(iface.trim()); }

if (addressAndPort == null || addressAndPort.trim().isEmpty()) {
    throw new IllegalArgumentException("interface address must be non-empty, e.g. 127.0.0.1:0");
}

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

try {
    InterfaceSearchAddress.parse(cfg);
} catch (IllegalArgumentException e) {
    if ("search address string is null or empty".equals(e.getMessage())) {
        // use default config value
    } else { throw e; }
}

When it happens

Trigger: Passing a null or empty string to InterfaceSearchAddress.parse(String addressAndPort), typically from driver configuration where the interface setting is unset or blank.

Common situations: Missing aeron.interface or similar config key; empty environment variable or system property substituted into the URI; config file with 'interface=' left blank.

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

• AeronArchive.Context.messageRetryAttempts must be > 0, got:
• applicationSpecificFeedback length must be equal to
• clientLivenessTimeoutNs=
• control has port=0 for subscription: channel=
• difference greater than 2^31 - 1: termId=

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

Appendix: source

Thrown at aeron-driver/src/main/java/io/aeron/driver/media/InterfaceSearchAddress.java:131

                    .append(ifc.isLoopback())
                    .append(", state: ")
                    .append(ifc.isUp() ? "UP" : "DOWN");
            }
        }

        return builder.toString();
    }

    static InterfaceSearchAddress wildcard()
    {
        return WILDCARD;
    }

    static InterfaceSearchAddress parse(final String addressAndPort) throws UnknownHostException
    {
        if (Strings.isEmpty(addressAndPort))
        {
            throw new IllegalArgumentException("search address string is null or empty");
        }

        int slashIndex = -1;
        int colonIndex = -1;
        int rightAngleBraceIndex = -1;

        for (int i = 0, length = addressAndPort.length(); i < length; i++)
        {
            switch (addressAndPort.charAt(i))
            {
                case '/':
                    slashIndex = i;
                    break;

                case ':':
                    colonIndex = i;
                    break;

View on GitHub (pinned to 6d60124e15)