aeron-io/aeron · error · IllegalArgumentException

invalid format:

Error message

invalid format: 

What it means

SocketAddressParser.parse throws IllegalArgumentException('invalid format: ' + nameAndPort) when the string is neither a valid IPv4 host:port nor a valid IPv6 [host]:port after name resolution. The parser uses small state machines (tryParseIpV4/tryParseIpV6) and rejects anything they cannot consume.

Solutions

1. Provide endpoint in canonical form: host:port for IPv4, [host]:port for IPv6, e.g. endpoint=[fe80::1]:40456
2. Verify the port is a valid integer and there is no whitespace or stray characters in the URI parameter
3. Check any custom NameResolver output — it must itself be a parseable address:port string

Example fix

// before
"aeron:udp?endpoint=fe80::1:40456" // unbracketed IPv6, unparseable
// after
"aeron:udp?endpoint=[fe80::1]:40456"

static boolean looksLikeAddressPort(String s) {
    if (s == null) return false;
    if (s.startsWith("[")) return s.matches("\[[0-9a-fA-F:.%]+\]:\d+");
    int c = s.indexOf(':');
    return c > 0 && c < s.length() - 1 && s.indexOf(':', c + 1) == -1;
}

When it happens

Trigger: Passing a string lacking host:port structure — e.g. 'localhost' with no port, 'host:port' where port is non-numeric, stray characters, or an unbracketed IPv6 address — to parse() after NameResolver.lookup.

Common situations: Typos in the aeron URI endpoint (missing :port); writing raw IPv6 like ::1:40456 without square brackets; whitespace inside the endpoint value; custom NameResolver returning a malformed or decorated address string.

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

• [address]:port is required for ipv6:
• input string must not be null or empty
• address:port is required for ipv4:
• Aeron URIs must start with 'aeron:', found
• bindAddressAndPort value too long:

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

Appendix: source

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

     * @return An {@link InetSocketAddress} for the parsed input.
     */
    static InetSocketAddress parse(
        final String value, final String uriParamName, final boolean isReResolution, final NameResolver nameResolver)
    {
        if (Strings.isEmpty(value))
        {
            throw new NullPointerException("input string must not be null or empty");
        }

        final String nameAndPort = nameResolver.lookup(value, uriParamName, isReResolution);
        ParseResult result = tryParseIpV4(nameAndPort);
        if (null == result)
        {
            result = tryParseIpV6(nameAndPort);
        }
        if (null == result)
        {
            throw new IllegalArgumentException("invalid format: " + nameAndPort);
        }

        final InetAddress inetAddress = nameResolver.resolve(result.host, uriParamName, isReResolution);
        return null == inetAddress ? InetSocketAddress.createUnresolved(result.host, result.port) :
        new InetSocketAddress(inetAddress, result.port);
    }

    static boolean isMulticastAddress(final String hostAndPort)
    {
        ParseResult result = tryParseIpV4(hostAndPort);
        if (null != result)
        {
            final String host = result.host;
            for (int i = 0, dotIndex = 0, end = host.length() - 1; i <= end; i++)
            {
                final char c = host.charAt(i);
                if ('.' == c || end == i)
                {

View on GitHub (pinned to 6d60124e15)