aeron-io/aeron · error · NumberFormatException

:port must be an integer value between 0 and 65535

Error message

:port must be an integer value between 0 and 65535

What it means

WildcardPortManager.parsePortRange parses a 'low-high' port range string for wildcard port allocation. Both endpoints are parsed as unsigned integers, and if either exceeds 65535 a NumberFormatException with this message is thrown. The caller then rethrows it as an IllegalArgumentException ('invalid port value ...'), so developers typically see the wrapping message.

Solutions

1. Ensure both bounds of the range string are integers in 0-65535, e.g. '10000-20000'.
2. Verify the range string format is exactly '<low>-<high>' with a dash and no spaces or extra characters.
3. If you need ports above 65535, that is impossible for UDP/TCP; lower the configured range.
4. Catch IllegalArgumentException at configuration load time and report the offending value to the operator.

Example fix

// before
WildcardPortManager mgr = new WildcardPortManager("0-99999", ...);
// after
WildcardPortManager mgr = new WildcardPortManager("0-65535", ...);

long low = Long.parseLong(parts[0]); long high = Long.parseLong(parts[1]);
if (low > 65535 || high > 65535) throw new IllegalArgumentException("port out of 0-65535: " + value);

try { new WildcardPortManager(value, ...); } catch (IllegalArgumentException e) { log.error("Bad port range {}: {}", value, e.getMessage()); throw new ConfigException(e); }

When it happens

Trigger: Passing a port-range config value (e.g. aeron.driver.ports.range style '10000-65535') where one bound is a number greater than 65535, or a value that Integer.parseUnsignedInt rejects (negative or non-numeric), e.g. '70000-65535' or '0-99999'.

Common situations: Typos in driver configuration, copying an IPv6 port-like component, or assuming the range endpoint can exceed the 16-bit TCP/UDP limit; also occurs when range syntax uses wrong separators so parseUnsignedInt fails.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• :low port value must be lower than high port value
• invalid port value
• className is empty
• failed to create Checksum instance for class: " + className
• existing Mark file type

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

Appendix: source

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

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

        return portRange;
    }

    private int findOpenPort()
    {
        for (int i = nextPort; i <= highPort; i++)

View on GitHub (pinned to 6d60124e15)