apache/flink · error · IllegalConfigurationException

Invalid port configuration. Port must be between 0and…

Error message

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

What it means

NetUtils.getPortRangeFromString validates every individual port in a port-range config string; a single (non-range) entry outside 0..65535 throws IllegalConfigurationException. The message (note the historical '0and' formatting typo) names the offending port. This is purely config validation, done before any socket is opened.

Solutions

Correct the port value in the config to be within 0..65535 (typically 1024..65535 in practice).
Check the exact value echoed in the message and the config key in the stack trace.
Add a config lint step validating port ranges before deployment.

Example fix

# before
rest.bind-port: 91234

# after
rest.bind-port: 9123

Defensive patterns

Strategy: validation

Validate before calling

static boolean isValidPort(int p) { return p >= 0 && p <= 65535; }
// apply to every token of the port-range config before startup

Try / catch

catch (IllegalConfigurationException e) { surface the offending config key to the deploy pipeline; treat as a deploy-time failure, not runtime. }

Prevention

Validate port configs in a pre-deploy lint step.
Prefer explicit single ports over ranges when possible.

When it happens

Trigger: A range string like '99999' or '0' style entries where isValidHostPort fails: port < 0 or > 65535, e.g. 'rest.bind-port: 70000' parsed as a single value; negative numbers like '-1' actually hit the range branch instead.

Common situations: Typos adding an extra digit (70000 instead of 7000); ports copied from another system with different limits; arithmetic building the port string overflowing.

Related errors

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

Appendix: source

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

     * @param rangeDefinition String describing a single port, a range of ports or multiple ranges.
     * @return Set of ports from the range definition
     * @throws NumberFormatException If an invalid string is passed.
     */
    public static Iterator<Integer> getPortRangeFromString(String rangeDefinition)
            throws NumberFormatException {
        final String[] ranges = rangeDefinition.trim().split(",");

        UnionIterator<Integer> iterators = new UnionIterator<>();

        for (String rawRange : ranges) {
            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)) {

View on GitHub (pinned to 2f3c205e92)