{"record":{"id":"565db22898acdffe","repo":"quarkusio/quarkus","slug":"port-number-range-must-be-within-d-d","errorCode":null,"errorMessage":"Port number range must be within [%d-%d]","messagePattern":"Port number range must be within \\[(.+?)-(.+?)\\]","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"extensions/kubernetes/vanilla/deployment/src/main/java/io/quarkus/kubernetes/deployment/BaseVanillaKubernetesProcessor.java","lineNumber":168,"sourceCode":"                context.add(new AddNodePortDecorator(context.name(), entry.getValue().nodePort().getAsInt(), entry.getKey()));\n            }\n        } else {\n            context.add(new AddNodePortDecorator(context.name(),\n                    config.nodePort().orElseGet(\n                            () -> getStablePortNumberInRange(context.name(), MIN_NODE_PORT_VALUE, MAX_NODE_PORT_VALUE)),\n                    config.ingress().targetPort()));\n        }\n    }\n\n    /**\n     * Given a string, generate a port number within the supplied range\n     * The output is always the same (between {@code min} and {@code max})\n     * given the same input and it's useful when we need to generate a port number\n     * which needs to stay the same but we don't care about the exact value\n     */\n    private static int getStablePortNumberInRange(String input, int min, int max) {\n        if (min < MIN_PORT_NUMBER || max > MAX_PORT_NUMBER) {\n            throw new IllegalArgumentException(\n                    String.format(\"Port number range must be within [%d-%d]\", MIN_PORT_NUMBER, MAX_PORT_NUMBER));\n        }\n\n        try {\n            byte[] hash = MessageDigest.getInstance(DEFAULT_HASH_ALGORITHM).digest(input.getBytes(StandardCharsets.UTF_8));\n            return min + new BigInteger(hash).mod(BigInteger.valueOf(max - min)).intValue();\n        } catch (Exception e) {\n            throw new RuntimeException(\"Unable to generate stable port number from input string: '\" + input + \"'\", e);\n        }\n    }\n}\n","sourceCodeStart":150,"sourceCodeEnd":180,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/kubernetes/vanilla/deployment/src/main/java/io/quarkus/kubernetes/deployment/BaseVanillaKubernetesProcessor.java#L150-L180","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\nint port = getStablePortNumberInRange(name, 80, 8080);\n// after\nint port = getStablePortNumberInRange(name, 1025, 65535);","handlingStrategy":"validation","validationCode":"if (min < 1025 || max > 65535 || min > max) throw new IllegalArgumentException(\"port range must be within [1025-65535]\");","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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"],"tags":["kubernetes","port-range","build-step"],"backgroundTag":"invalid-port-range","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}