What causes "Port number range must be within [%d-%d]" in quarkusio/quarkus?

Use a min of at least MIN_PORT_NUMBER (1025) and a max of at most MAX_PORT_NUMBER (65535) when requesting the stable port

quarkusio/quarkus · error · IllegalArgumentException

Port number range must be within [%d-%d]

Error message

Port number range must be within [%d-%d]

What it means

BaseVanillaKubernetesProcessor.getStablePortNumberInRange derives a deterministic port from a string hash. It validates upfront that the requested [min,max] range lies within the allowed port bounds (MIN_PORT_NUMBER..MAX_PORT_NUMBER, 1025-65535 in this class); if not, it throws IllegalArgumentException so a bad caller is caught before any hashing.

Source

Thrown at extensions/kubernetes/vanilla/deployment/src/main/java/io/quarkus/kubernetes/deployment/BaseVanillaKubernetesProcessor.java:168

                context.add(new AddNodePortDecorator(context.name(), entry.getValue().nodePort().getAsInt(), entry.getKey()));
            }
        } else {
            context.add(new AddNodePortDecorator(context.name(),
                    config.nodePort().orElseGet(
                            () -> getStablePortNumberInRange(context.name(), MIN_NODE_PORT_VALUE, MAX_NODE_PORT_VALUE)),
                    config.ingress().targetPort()));
        }
    }

    /**
     * Given a string, generate a port number within the supplied range
     * The output is always the same (between {@code min} and {@code max})
     * given the same input and it's useful when we need to generate a port number
     * which needs to stay the same but we don't care about the exact value
     */
    private static int getStablePortNumberInRange(String input, int min, int max) {
        if (min < MIN_PORT_NUMBER || max > MAX_PORT_NUMBER) {
            throw new IllegalArgumentException(
                    String.format("Port number range must be within [%d-%d]", MIN_PORT_NUMBER, MAX_PORT_NUMBER));
        }

        try {
            byte[] hash = MessageDigest.getInstance(DEFAULT_HASH_ALGORITHM).digest(input.getBytes(StandardCharsets.UTF_8));
            return min + new BigInteger(hash).mod(BigInteger.valueOf(max - min)).intValue();
        } catch (Exception e) {
            throw new RuntimeException("Unable to generate stable port number from input string: '" + input + "'", e);
        }
    }
}

View on GitHub (pinned to e1c734241f)

Solutions

Use a min of at least MIN_PORT_NUMBER (1025) and a max of at most MAX_PORT_NUMBER (65535) when requesting the stable port
If the user wants a well-known port like 80/443, configure it explicitly on the service instead of via the stable-port generator
Check the quarkus.kubernetes port configuration values for values below 1025 or above 65535

Example fix

// before
int port = getStablePortNumberInRange(name, 80, 8080);
// after
int port = getStablePortNumberInRange(name, 1025, 65535);

Defensive patterns

Strategy: validation

Validate before calling

if (min < 1025 || max > 65535 || min > max) throw new IllegalArgumentException("port range must be within [1025-65535]");

Prevention

Only request ports in 1025-65535 for generated stable ports
Keep well-known ports (80/443) as explicit config, not hashed values
Log the min/max used when calling the generator to make range bugs obvious

When it happens

Trigger: Calling getStablePortNumberInRange (directly or via the service() build step when generating a stable port for a service) with min < MIN_PORT_NUMBER or max > MAX_PORT_NUMBER.

Common situations: Custom build steps or config values requesting reserved/privileged ports (e.g. 1-1024 like port 80/443) or out-of-range values above 65535 for the generated Kubernetes service port.

Related errors

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/565db22898acdffe. Report an issue: GitHub.