What causes "All Kubernetes ports must be unique - " in quarkusio/quarkus?

Change one of the conflicting ports to a distinct value (e.g. management port to 9000)

quarkusio/quarkus · error · IllegalArgumentException

All Kubernetes ports must be unique -

Error message

All Kubernetes ports must be unique -

What it means

Also in KubernetesCommonHelper.verifyPorts: after checking name uniqueness it enforces that the numeric port values themselves are not reused by two enabled ports, since a Kubernetes container can bind each port number once. Violations throw IllegalArgumentException naming the duplicated port number.

Source

Thrown at extensions/kubernetes/vanilla/deployment/src/main/java/io/quarkus/kubernetes/deployment/KubernetesCommonHelper.java:147

    public static boolean isNotNullOrEmpty(String string) {
        return string != null && !string.isEmpty();
    }

    private static Map<String, Integer> verifyPorts(List<KubernetesPortBuildItem> kubernetesPortBuildItems) {
        final Map<String, Integer> result = new HashMap<>();
        final Set<Integer> usedPorts = new HashSet<>();
        for (KubernetesPortBuildItem entry : kubernetesPortBuildItems) {
            if (!entry.isEnabled()) {
                continue;
            }
            final String name = entry.getName();
            if (result.containsKey(name)) {
                throw new IllegalArgumentException(
                        "All Kubernetes ports must have unique names - " + name + " has been used multiple times");
            }
            final Integer port = entry.getPort();
            if (usedPorts.contains(port)) {
                throw new IllegalArgumentException(
                        "All Kubernetes ports must be unique - " + port + " has been used multiple times");
            }
            result.put(name, port);
            usedPorts.add(port);
        }
        return result;
    }

    /**
     * Creates the configurator build items.
     */
    public static void printMessageAboutPortsThatCantChange(String target, List<KubernetesPortBuildItem> ports,
            PlatformConfiguration configuration) {
        ports.forEach(port -> {
            boolean enabled = port.isEnabled() || configuration.ports().containsKey(port.getName());
            if (enabled) {
                String name = "quarkus." + target + ".ports." + port.getName() + ".container-port";
                Optional<Integer> value = Optional.ofNullable(configuration.ports().get(port.getName()))

View on GitHub (pinned to e1c734241f)

Solutions

Change one of the conflicting ports to a distinct value (e.g. management port to 9000)
Disable one of the duplicate port build items if it is redundant
Review quarkus.http.port / quarkus.management.port and any custom KubernetesPortBuildItem producers for collisions

Example fix

// before
quarkus.http.port=8080
quarkus.management.port=8080
// after
quarkus.http.port=8080
quarkus.management.port=9000

Defensive patterns

Strategy: validation

Validate before calling

Set<Integer> used = new HashSet<>();
for (KubernetesPortBuildItem p : ports) {
    if (!used.add(p.getPort())) throw new IllegalArgumentException("duplicate port: " + p.getPort());
}

Prevention

Keep http and management ports distinct (e.g. 8080 vs 9000)
Centralize port constants in config to prevent drift
Before building, grep config for quarkus.*.port values and check uniqueness

When it happens

Trigger: Two enabled KubernetesPortBuildItems expose the same integer port value (e.g. two services both mapped to 8080) during manifest generation.

Common situations: quarkus.http.port and a custom port build item both set to 8080; management port mistakenly equal to the HTTP port; a container image exposing the same port via two entries.

Related errors

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