quarkusio/quarkus · error · RuntimeException

Failed to configure OpenShift. Make sure you have the Quarku

Error message

Failed to configure OpenShift. Make sure you have the Quarkus OpenShift extension.

What it means

The OpenshiftDeployer tries to build a Kubernetes client and adapt it to an OpenShiftClient to check the cluster. Any exception while creating/configuring that client (connection failure, missing extension classes, bad kubeconfig) is wrapped in this RuntimeException, which advises that the Quarkus OpenShift extension may be missing.

Source

Thrown at extensions/kubernetes/vanilla/deployment/src/main/java/io/quarkus/kubernetes/deployment/OpenshiftDeployer.java:36

    @BuildStep
    public void checkEnvironment(Optional<SelectedKubernetesDeploymentTargetBuildItem> selectedDeploymentTarget,
            List<GeneratedKubernetesResourceBuildItem> resources,
            KubernetesClientBuildItem kubernetesClientBuilder,
            BuildProducer<KubernetesDeploymentClusterBuildItem> deploymentCluster) {
        selectedDeploymentTarget.ifPresent(target -> {
            if (!KubernetesDeploy.INSTANCE.checkSilently(kubernetesClientBuilder)) {
                return;
            }
            if (target.getEntry().getName().equals(OPENSHIFT)) {
                try (var openShiftClient = kubernetesClientBuilder.buildClient().adapt(OpenShiftClient.class)) {
                    if (openShiftClient.hasApiGroup("openshift.io", false)) {
                        deploymentCluster.produce(new KubernetesDeploymentClusterBuildItem(OPENSHIFT));
                    } else {
                        throw new IllegalStateException(
                                "Openshift was requested as a deployment, but the target cluster is not an Openshift cluster!");
                    }
                } catch (Exception e) {
                    throw new RuntimeException(
                            "Failed to configure OpenShift. Make sure you have the Quarkus OpenShift extension.", e);
                }
            }
        });
    }
}

View on GitHub (pinned to e1c734241f)

Solutions

  1. Add the Quarkus OpenShift extension: ./mvnw quarkus:add-extension -Dextensions=quarkus-openshift (or add io.quarkus:quarkus-openshift dependency).
  2. Fix cluster connectivity: verify 'kubectl cluster-info' / 'oc whoami' with the same KUBECONFIG used by the build.
  3. Correct or regenerate the kubeconfig file referenced by your environment/config.

Example fix

// before (pom.xml)
<!-- only quarkus-kubernetes present -->
// after
<dependency>
  <groupId>io.quarkus</groupId>
  <artifactId>quarkus-openshift</artifactId>
</dependency>
Defensive patterns

Strategy: validation

Validate before calling

// Ensure the OpenShift client capability is present and the cluster is reachable before deploying
Class.forName("io.fabric8.openshift.client.OpenShiftClient"); // throws if extension/client missing
try (var c = new KubernetesClientBuilder().build().adapt(OpenShiftClient.class)) {
    c.getConfiguration(); // forces connection setup; surfaces config errors early
}

Try / catch

try {
    deploy();
} catch (RuntimeException e) {
    if (e.getMessage().startsWith("Failed to configure OpenShift")) {
        LOGGER.error("Install quarkus-openshift or fix cluster connectivity", e);
        throw new BuildFailure("OpenShift deploy prerequisite missing", e);
    }
    throw e;
}

Prevention

When it happens

Trigger: An exception (any Exception) is thrown while building the client or calling hasApiGroup in checkEnvironment — e.g. unreachable cluster, invalid kubeconfig, or the kubernetes-client OpenShift capability not present because the quarkus-openshift extension is not installed.

Common situations: Using quarkus.kubernetes-client without the quarkus-openshift extension while deploying to OpenShift; cluster unreachable/wrong context in CI; malformed KUBECONFIG file.

Related errors

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