aeron-io/aeron · error · IllegalArgumentException

[address]:port is required for ipv6:

Error message

[address]:port is required for ipv6: 

What it means

tryParseIpV6 throws IllegalArgumentException('[address]:port is required for ipv6: ' + str) when an IPv6 string is missing the mandatory [address]:port bracket structure. IPv6 contains ':' characters itself, so Aeron requires square brackets to disambiguate the address from the port, and rejects strings not matching that shape.

Solutions

1. Wrap the IPv6 address in square brackets and append the port: endpoint=[::1]:40456
2. Include a numeric port after the closing bracket — '[fe80::1%eth0]:40456' is valid, '[fe80::1%eth0]' is not
3. If possible use IPv4 endpoints to avoid bracket-syntax pitfalls in generated configuration

Example fix

// before
"aeron:udp?endpoint=::1:40456"
// after
"aeron:udp?endpoint=[::1]:40456"

static boolean isValidIpv6Endpoint(String s) {
    return s != null && s.matches("\[[0-9a-fA-F:.%]+\]:\d+");
}

When it happens

Trigger: Passing '::1' or 'fe80::1' without brackets, '[::1]' without a port, or a bracketed form whose port portion is absent/non-numeric into tryParseIpV6 (via parse or isMulticastAddress).

Common situations: IPv6 endpoints written without brackets in aeron:udp URIs; forgetting the port after the bracket; OS-generated link-local strings like fe80::1%eth0 pasted without the [host]:port wrapper.

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

• invalid format:
• address:port is required for ipv4:
• input string must not be null or empty
• 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/3f41c067b83a5fb3. Report an issue: GitHub.

Appendix: source

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

                case PORT:
                    if (c < '0' || '9' < c)
                    {
                        return null;
                    }
                    break;
            }
        }

        if (-1 != portIndex && 1 < length - portIndex)
        {
            final String hostname = str.substring(1, scopeIndex != -1 ? scopeIndex : portIndex - 1);
            portIndex++;
            final int port = AsciiEncoding.parseIntAscii(str, portIndex, length - portIndex);
            return new ParseResult(hostname, port);
        }

        throw new IllegalArgumentException("[address]:port is required for ipv6: " + str);
    }

    private static final class ParseResult
    {
        final String host;
        final int port;

        private ParseResult(final String host, final int port)
        {
            this.host = host;
            this.port = port;
        }
    }
}

View on GitHub (pinned to 6d60124e15)