What causes "invalid port value ${value}" in aeron-io/aeron?

Inspect the cause (getCause()) to see whether it was a parse failure, out-of-range, or ordering problem.

aeron-io/aeron · error · IllegalArgumentException

invalid port value

Error message

invalid port value ${value}

What it means

This is the wrapping IllegalArgumentException thrown in parsePortRange's catch block whenever the raw range string fails parsing or validation (non-numeric, >65535, or low>high). The original NumberFormatException is attached as the cause, and the offending value is included in the message.

Solutions

Inspect the cause (getCause()) to see whether it was a parse failure, out-of-range, or ordering problem.
Correct the range string to '<low>-<high>' with both values in 0-65535 and low <= high.
Add startup-time validation of the config value before constructing the driver media layer.
Log the exact configured value so operators can spot placeholder or typo issues.

Example fix

// before
String range = System.getProperty("aeron.ports", "${range}");
// after
String range = System.getProperty("aeron.ports", "10000-20000");

Defensive patterns

Strategy: try-catch

Validate before calling

java.util.regex.Pattern RANGE = Pattern.compile("^(\\d+)-(\\d+)$");
Matcher m = RANGE.matcher(value); if (!m.matches()) throw new IllegalArgumentException("bad range: " + value);

Try / catch

try { parse(value); } catch (IllegalArgumentException e) { log.error("port range '{}' invalid, cause: {}", value, e.getCause()); }

Prevention

Always inspect getCause() to distinguish parse vs range vs ordering failures
Reject placeholders and empty values before parsing
Centralize range parsing in one validated helper

When it happens

Trigger: Any malformed wildcard port-range value passed to WildcardPortManager: non-numeric text, negative numbers, bounds over 65535, or reversed bounds.

Common situations: Environment variables or property files supplying the driver's wildcard port range with typos, wrong separators (',' instead of '-'), or unset placeholders like '${range}' reaching the parser.

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

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

Appendix: source

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

        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");
            }
        }
        catch (final NumberFormatException ex)
        {
            throw new IllegalArgumentException("invalid port value " + value, ex);
        }

        return portRange;
    }

    private int findOpenPort()
    {
        for (int i = nextPort; i <= highPort; i++)
        {
            if (!portSet.contains(i))
            {
                return i;
            }
        }

        for (int i = lowPort; i < nextPort; i++)
        {
            if (!portSet.contains(i))

View on GitHub (pinned to 6d60124e15)