aeron-io/aeron · error · IllegalArgumentException

port range "" incorrect format

Error message

port range "" incorrect format

What it means

WildcardPortManager.parsePortRange expects a port range value of the form '<min> <max>' (two whitespace-separated integers). A value that does not split into exactly two tokens produces IllegalArgumentException naming the offending value.

Solutions

1. Format the value as two space-separated numbers, e.g. '40000 40100'.
2. Do not use hyphens, colons, or commas as separators.
3. Check quoting in your config/launcher so the space is preserved (shell/properties escaping).

Example fix

// before
-Daeron.wildcard.port.range=40000-40100
// after
-Daeron.wildcard.port.range="40000 40100"

String[] parts = rangeStr.trim().split(" +");
if (parts.length != 2) {
    throw new IllegalArgumentException("port range must be '<min> <max>', got: " + rangeStr);
}

try {
    portManager.parsePortRange(value);
} catch (IllegalArgumentException e) {
    logger.error("bad port range: {}", e.getMessage());
    // correct to space-separated form and reload config
}

When it happens

Trigger: Configuring the wildcard port range system property (aeron.wildcard.port.range) with zero, one, or three tokens — e.g. '40000', '40000-40100' (hyphen instead of space), or an empty string — then parsing the port range.

Common situations: Using '40000-40100' or '40000:40100' syntax instead of the required space-separated form, quoting issues stripping the space, or an unset/empty property.

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

• AeronArchive.Context.messageRetryAttempts must be > 0, got:
• AeronCluster.Context.clientName length must be <=…
• AeronCluster.Context ingressEndpoints must be null when…
• applicationSpecificFeedback length must be equal to
• clientLivenessTimeoutNs=

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

Appendix: source

Thrown at aeron-driver/src/main/java/io/aeron/driver/media/WildcardPortManager.java:112

    }

    /**
     * Parse a port range in the format "low high".
     *
     * @param value for the port range in string format.
     * @return port range as low index 0 and high index 1.
     */
    public static int[] parsePortRange(final String value)
    {
        if (null == value || value.isEmpty())
        {
            return EMPTY_PORT_RANGE;
        }

        final String[] ports = value.split(" +");
        if (ports.length != 2)
        {
            throw new IllegalArgumentException("port range \"" + value + "\" incorrect format");
        }

        final int[] portRange = new int[2];

        try
        {
            portRange[0] = Integer.parseUnsignedInt(ports[0]);
            portRange[1] = Integer.parseUnsignedInt(ports[1]);

            if (portRange[0] > 65535 || portRange[1] > 65535)
            {
                throw new NumberFormatException(value + ":port must be an integer value between 0 and 65535");
            }

            if (portRange[0] > portRange[1])
            {
                throw new NumberFormatException(value + ":low port value must be lower than high port value");
            }

View on GitHub (pinned to 6d60124e15)