apache/flink · error · IllegalConfigurationException

Invalid port configuration. Port range end must be bigger th

Q: What causes "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. Given range: {}" in apache/flink?

If you meant one port, write it without the range: '8081' not '8081-8081'.

Error message

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. Given range: {}

What it means

For a 'start-end' range entry, NetUtils.getPortRangeFromString requires start < end strictly; equal or inverted bounds throw IllegalConfigurationException. The message explicitly suggests providing a single port directly instead of a one-element range. This avoids generating empty or ambiguous iterators.

Source

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

                // 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."
                                    + " Given range: "
                                    + range);
                }
                rangeIterator =
                        new Iterator<Integer>() {
                            int i = start;

                            @Override
                            public boolean hasNext() {
                                return i <= end;
                            }

                            @Override
                            public Integer next() {
                                return i++;

View on GitHub (pinned to 2f3c205e92)

Solutions

If you meant one port, write it without the range: '8081' not '8081-8081'.
If a range is intended, make the end strictly larger than the start.
When generating ranges from variables, add an assertion start < end before deployment.

Example fix

# before
rest.bind-port: 8081-8081

# after
rest.bind-port: 8081

Defensive patterns

Strategy: validation

Validate before calling

static String normalizeRange(String def) {
    String[] b = def.split("-", 2);
    if (b.length == 2 && b[0].equals(b[1])) return b[0]; // 'x-x' -> 'x'
    return def;
}

Prevention

Write single ports as single ports.
When generating ranges from variables, assert start < end.

When it happens

Trigger: Config values like '8081-8081' (equal bounds) or '8081-8080' (inverted); parameterized configs where start and end come from the same variable.

Common situations: Templates defaulting both range ends to the same port; automation writing '<p>-<p>' for a fixed port; copy-paste edits flipping the two numbers.

Related errors

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