apache/flink · error · IllegalConfigurationException

Invalid port range: "{}"

Error message

Invalid port range: "{}"

What it means

PortRange's constructor delegates the range string to NetUtils.getPortRangeFromString; if parsing hits a NumberFormatException (non-numeric token), it rethrows as IllegalConfigurationException quoting the whole range. This is the typed wrapper used when port-range configs are bound to PortRange objects. Note it only catches NumberFormatException — range-order and bound-validation errors from NetUtils propagate with their own messages.

Source

Thrown at flink-core/src/main/java/org/apache/flink/util/PortRange.java:48

    private final String portRange;
    private final Iterator<Integer> portsIterator;

    public PortRange(int port) {
        this(String.valueOf(port));
    }

    /**
     * Creates a new port range instance.
     *
     * @param portRange given port range string
     * @throws IllegalConfigurationException if given port range string is invalid
     */
    public PortRange(String portRange) {
        this.portRange = checkNotNull(portRange);
        try {
            portsIterator = NetUtils.getPortRangeFromString(portRange);
        } catch (NumberFormatException e) {
            throw new IllegalConfigurationException("Invalid port range: \"" + portRange + "\"");
        }
    }

    public Iterator<Integer> getPortsIterator() {
        return portsIterator;
    }

    @Override
    public String toString() {
        return portRange;
    }
}

View on GitHub (pinned to 2f3c205e92)

Solutions

1. Check the quoted range string in the message and correct it to integer tokens ('8081', '8081-8090').
2. Ensure templating actually substituted port variables before the config reaches Flink.
3. Add a config smoke test asserting the port-range string matches \d+(-\d+)? patterns.

Example fix

# before
rest.bind-port: ${PORT_RANGE} # unsubstituted

# after
rest.bind-port: 8081-8090

static final java.util.regex.Pattern PORT_RANGE = java.util.regex.Pattern.compile("^\\d+(-\\d+)?(,\\d+(-\\d+)?)*$");
if (!PORT_RANGE.matcher(rangeDef.trim()).matches()) { throw new IllegalArgumentException("bad port range: " + rangeDef); }

catch (IllegalConfigurationException e) { if (e.getMessage().startsWith("Invalid port range")) { /* reject the config/deploy artifact with the quoted value */ } }

When it happens

Trigger: Constructing new PortRange("abc"), "8081-https", "9000-" or any range containing a non-integer token; configs like 'rest.port: rest_port' where a variable was never substituted.

Common situations: Unsubstituted template placeholders ('${port}') in YAML; typos; environment-specific configs where the port field got a service name instead of a number.

Related errors

• Invalid port configuration. Port must be between 0and 65535,
• 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
• 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/e48cc27957f204dc. Report an issue: GitHub.