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 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.

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)

Solutions

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

Example fix

# before
rest.bind-port: 91234

# after
rest.bind-port: 9123

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

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

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

• 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/5c0ea02825a1efb1. Report an issue: GitHub.