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

Give each port a unique name, e.g. quarkus.kubernetes.ports. .name or distinct KubernetesPortBuildItem names

quarkusio/quarkus · error · IllegalArgumentException

All Kubernetes ports must have unique names -

Error message

All Kubernetes ports must have unique names -

What it means

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.

Source

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

            activePorts.put(name, combinedPort);
        });
        return activePorts;
    }

    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) {

View on GitHub (pinned to e1c734241f)

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

Example fix

// before
new KubernetesPortBuildItem("http", 8080, true)
new KubernetesPortBuildItem("http", 8081, true)
// after
new KubernetesPortBuildItem("http", 8080, true)
new KubernetesPortBuildItem("management", 9000, true)

Defensive patterns

Strategy: validation

Validate before calling

Set<String> seen = new HashSet<>();
for (KubernetesPortBuildItem p : ports) {
    if (!seen.add(p.getName())) throw new IllegalArgumentException("duplicate port name: " + p.getName());
}

Prevention

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

When it happens

Trigger: Two or more enabled @BuildStep-produced KubernetesPortBuildItems share the same name (default 'http' collisions included) when generating the manifest.

Common situations: 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.

Related errors

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