{"record":{"id":"829d001773797175","repo":"quarkusio/quarkus","slug":"all-kubernetes-ports-must-have-unique-names","errorCode":null,"errorMessage":"All Kubernetes ports must have unique names - ","messagePattern":"All Kubernetes ports must have unique names - ","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"extensions/kubernetes/vanilla/deployment/src/main/java/io/quarkus/kubernetes/deployment/KubernetesCommonHelper.java","lineNumber":142,"sourceCode":"            activePorts.put(name, combinedPort);\n        });\n        return activePorts;\n    }\n\n    public static boolean isNotNullOrEmpty(String string) {\n        return string != null && !string.isEmpty();\n    }\n\n    private static Map<String, Integer> verifyPorts(List<KubernetesPortBuildItem> kubernetesPortBuildItems) {\n        final Map<String, Integer> result = new HashMap<>();\n        final Set<Integer> usedPorts = new HashSet<>();\n        for (KubernetesPortBuildItem entry : kubernetesPortBuildItems) {\n            if (!entry.isEnabled()) {\n                continue;\n            }\n            final String name = entry.getName();\n            if (result.containsKey(name)) {\n                throw new IllegalArgumentException(\n                        \"All Kubernetes ports must have unique names - \" + name + \" has been used multiple times\");\n            }\n            final Integer port = entry.getPort();\n            if (usedPorts.contains(port)) {\n                throw new IllegalArgumentException(\n                        \"All Kubernetes ports must be unique - \" + port + \" has been used multiple times\");\n            }\n            result.put(name, port);\n            usedPorts.add(port);\n        }\n        return result;\n    }\n\n    /**\n     * Creates the configurator build items.\n     */\n    public static void printMessageAboutPortsThatCantChange(String target, List<KubernetesPortBuildItem> ports,\n            PlatformConfiguration configuration) {","sourceCodeStart":124,"sourceCodeEnd":160,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/kubernetes/vanilla/deployment/src/main/java/io/quarkus/kubernetes/deployment/KubernetesCommonHelper.java#L124-L160","documentation":"KubernetesCommonHelper.verifyPorts (invoked while combining all KubernetesPortBuildItems) enforces that every enabled Kubernetes port has a distinct name, because Kubernetes container/service ports are keyed by name. A duplicate name aborts the build with IllegalArgumentException naming the duplicated port name.","triggerScenarios":"Two or more enabled @BuildStep-produced KubernetesPortBuildItems share the same name (default 'http' collisions included) when generating the manifest.","commonSituations":"Multiple extensions each registering a port named 'http'; the application exposes two HTTP endpoints via config quarkus.http.*-port build items with identical names; custom code adding ports with clashing names.","solutions":["Give each port a unique name, e.g. quarkus.kubernetes.ports.<name>.name or distinct KubernetesPortBuildItem names","Disable the duplicate port if it is not needed (setEnabled(false) on the build item)","If both ports are the same HTTP port registered twice, remove one registration instead of renaming"],"exampleFix":"// before\nnew KubernetesPortBuildItem(\"http\", 8080, true)\nnew KubernetesPortBuildItem(\"http\", 8081, true)\n// after\nnew KubernetesPortBuildItem(\"http\", 8080, true)\nnew KubernetesPortBuildItem(\"management\", 9000, true)","handlingStrategy":"validation","validationCode":"Set<String> seen = new HashSet<>();\nfor (KubernetesPortBuildItem p : ports) {\n    if (!seen.add(p.getName())) throw new IllegalArgumentException(\"duplicate port name: \" + p.getName());\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Name ports after their role (http, management, grpc) to avoid 'http' collisions","Audit extensions that register default 'http' ports alongside yours","Keep a single producer of the primary HTTP port build item"],"tags":["kubernetes","ports","duplicate-name"],"backgroundTag":"duplicate-port-name","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"}