apache/flink · error · IllegalConfigurationException

Invalid port configuration. Port must be between 0and 65535,

Error message

Invalid port configuration. Port must be between 0and 65535, but range start was {}.

What it means

When NetUtils.getPortRangeFromString parses an entry containing '-' as a range, it validates the start value; a start outside 0..65535 throws IllegalConfigurationException with 'range start was <n>'. Only the start bound is reported by this specific message. Same validation as the single-port case, applied to range[0].

Source

Thrown at flink-core/src/main/java/org/apache/flink/util/NetUtils.java:436

            Iterator<Integer> rangeIterator;
            String range = rawRange.trim();
            int dashIdx = range.indexOf('-');
            if (dashIdx == -1) {
                // only one port in range:
                final int port = Integer.parseInt(range);
                if (!isValidHostPort(port)) {
                    throw new IllegalConfigurationException(
                            "Invalid port configuration. Port must be between 0"
                                    + "and 65535, but was "
                                    + port
                                    + ".");
                }
                rangeIterator = Collections.singleton(Integer.valueOf(range)).iterator();
            } else {
                // evaluate range
                final int start = Integer.parseInt(range.substring(0, dashIdx));
                if (!isValidHostPort(start)) {
                    throw new IllegalConfigurationException(
                            "Invalid port configuration. Port must be between 0"
                                    + "and 65535, but range start was "
                                    + start
                                    + ".");
                }
                final int end = Integer.parseInt(range.substring(dashIdx + 1));
                if (!isValidHostPort(end)) {
                    throw new IllegalConfigurationException(
                            "Invalid port configuration. Port must be between 0"
                                    + "and 65535, but range end was "
                                    + end
                                    + ".");
                }
                if (start >= end) {
                    throw new IllegalConfigurationException(
                            "Invalid port configuration."
                                    + " Port range end must be bigger than port range start."
                                    + " If you wish to use single port please provide the value directly, not as a range."

View on GitHub (pinned to 2f3c205e92)

Solutions

1. Fix the start value in the range to a valid port (0..65535).
2. Re-check the whole range string since the end bound is validated right after — fix both at once.
3. Prefer explicit single ports unless a range is genuinely needed.

Example fix

# before
rest.bind-port: 70000-70100

# after
rest.bind-port: 7000-7100

static void validatePortRange(String def) {
    for (String part : def.split(",")) {
        String r = part.trim();
        int dash = r.indexOf('-');
        int start = Integer.parseInt(dash < 0 ? r : r.substring(0, dash));
        Preconditions.checkArgument(start >= 0 && start <= 65535, "bad range start: %s", r);
    }
}

When it happens

Trigger: Range strings like '70000-70100' or '-100-100' style values whose first parsed integer fails isValidHostPort; e.g. config 'rest.bind-port: 99999-100000'.

Common situations: Mistyped range boundaries; ranges generated programmatically with off-by-orders-of-magnitude errors; configs migrated from systems allowing wider port numbers.

Related errors

• Invalid port configuration. Port must be between 0and 65535,
• Invalid port configuration. Port must be between 0and 65535,
• Invalid port configuration. Port range end must be bigger th
• Invalid port range: "{}"
• Value for config option %s must be one of %s (was %s)

AI-assisted analysis of apache/flink@2f3c205e92 (2026-08-14). Data as JSON: /api/errors/cd0852cae6fd47b6. Report an issue: GitHub.