aeron-io/aeron · error · IllegalArgumentException

expected format is ' ' or ' :port', but got

Error message

expected format is '{interface_name}' or '{interface_name}:port', but got '{str}'

What it means

NamedInterface.parse (Java driver media layer) parses an interface specification of the form '{interface_name}' or '{interface_name}:port'. If the string is empty or does not start with the opening '{' character, or has no closing '}' at a plausible position, it throws a parse exception with this message.

Solutions

1. Wrap the interface name in curly braces: '{eth0}:40456' or '{eth0}'.
2. Trim surrounding whitespace and verify the value is non-empty and starts with '{' and contains '}'.
3. If you just want to bind by address, use a plain IP form (e.g. '192.168.1.10:40456') instead of the named-interface form.

Example fix

// before (driver config)
DatagramChannel: interface=eth0:40456
// after
DatagramChannel: interface={eth0}:40456

String trimmed = str == null ? "" : str.trim(); boolean ok = trimmed.startsWith("{") && trimmed.indexOf('}') > 1; if (!ok) throw new IllegalArgumentException("use {name} or {name}:port, got: " + str);

try { NamedInterface.parse(value); } catch (IllegalArgumentException e) { log.warn("Bad interface spec, expected {name} or {name}:port: " + value); }

When it happens

Trigger: Driver configuration properties such as aeron.driver.interfaces or UDP transport 'interface'/'control' endpoints containing a named-interface string that is missing the braces, empty, or malformed (e.g. 'eth0:40456' instead of '{eth0}:40456').

Common situations: Setting AERON_DRIVER_CONFIGURATION or driver properties with a bare NIC name or IP without the required '{...}' wrapper; copying a bind address format from another framework; shell escaping stripping braces; stray whitespace before the '{'.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• Active media driver detected
• Aeron client instance must set…
• Aeron client must use a RethrowingErrorHandler
• Aeron client must use a RethrowingErrorHandler
• AeronArchive.Context.controlRequestChannel must be set

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

Appendix: source

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

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

        throw new IllegalStateException(
            "no " + protocolFamily + " addresses found on interface " + localInterface.getName());
    }

    static NamedInterface parse(final String str)
    {
        if (Strings.isEmpty(str) || str.charAt(0) != OPENING_CHAR)
        {
            throw parseException(str);
        }

        final int nameEnd = str.lastIndexOf('}');
        if (nameEnd <= 1)
        {
            throw parseException(str);
        }
        final String name = str.substring(1, nameEnd);

        int port = 0;
        final int trailing = str.length() - nameEnd - 1;
        if (trailing > 0)
        {
            if (trailing == 1 || str.charAt(nameEnd + 1) != ':')
            {
                throw parseException(str);
            }

View on GitHub (pinned to 6d60124e15)