aeron-io/aeron · error · IllegalArgumentException

address:port is required for ipv4:

Error message

address:port is required for ipv4: 

What it means

tryParseIpV4 throws IllegalArgumentException('address:port is required for ipv4: ' + str) when a string intended as IPv4 lacks the required host:port structure — most often the port portion is missing or the string does not contain a ':' separator at a valid position. It is a precise, IPv4-specific format check inside the state-machine parser.

Solutions

1. Append the port to the IPv4 address, e.g. endpoint=192.168.1.10:40456
2. Verify any string templates or environment variables supplying the endpoint render both host and port
3. Validate with a regex like ^\d{1,3}(\.\d{1,3}){3}:\d+$ before passing to Aeron

Example fix

// before
"aeron:udp?endpoint=192.168.1.10"
// after
"aeron:udp?endpoint=192.168.1.10:40456"

static boolean isValidIpv4Endpoint(String s) {
    return s != null && s.matches("\d{1,3}(\.\d{1,3}){3}:\d+");
}

When it happens

Trigger: Parsing endpoints like '127.0.0.1' (no port), '127.0.0.1:' (empty port), ':40456' (no host), or strings where AsciiEncoding.parseIntAscii fails on the port digits.

Common situations: URI templates where the port variable was not substituted (endpoint=${host}); truncating the endpoint when building URIs programmatically; copy/paste dropping the port.

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
• invalid format:
• Aeron URIs must start with 'aeron:', found
• 'control-mode=dynamic' requires that 'control' parameter is…

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

Appendix: source

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

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

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

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

    private static ParseResult tryParseIpV6(final String str)
    {
        IpV6State state = IpV6State.START_ADDR;
        int portIndex = -1;
        int scopeIndex = -1;
        final int length = str.length();

        for (int i = 0; i < length; i++)
        {
            final char c = str.charAt(i);

            switch (state)
            {
                case START_ADDR:
                    if ('[' == c)
                    {

View on GitHub (pinned to 6d60124e15)