apache/dolphinscheduler · error · RuntimeException

fail to get k8s ApiClient:%s

Error message

fail to get k8s ApiClient:%s

What it means

K8sManager.createK8sClientInner wraps any failure to build a KubernetesClient for a cluster (clusterCode -> configYaml from the cluster table) in a RuntimeException with this message. getClient() parses the kubeconfig YAML and constructs a client via fabric8 KubernetesClientBuilder; any parse or construction error is rethrown here. The root cause's stack trace is only logged, not propagated.

Source

Thrown at dolphinscheduler-api/src/main/java/org/apache/dolphinscheduler/api/k8s/K8sManager.java:115

            client.close();
        }
    }

    private void createK8sClientInner(Long clusterCode) {
        Cluster cluster = clusterDao.queryByClusterCode(clusterCode);
        if (cluster == null) {
            return;
        }

        String k8sConfig = ClusterConfUtils.getK8sConfig(cluster.getConfig());
        if (k8sConfig != null) {
            KubernetesClient client = null;
            try {
                client = getClient(k8sConfig);
                clientMap.put(clusterCode, client);
            } catch (Exception e) {
                log.error("cluster code ={},fail to get k8s ApiClient:  {}", clusterCode, e.getMessage());
                throw new RuntimeException("fail to get k8s ApiClient:" + e.getMessage());
            }
        }
    }

    private KubernetesClient getClient(String configYaml) throws RuntimeException {
        try {
            Config config = Config.fromKubeconfig(configYaml);
            return new KubernetesClientBuilder().withConfig(config).build();
        } catch (Exception e) {
            log.error("Fail to get k8s ApiClient", e);
            throw new RuntimeException("fail to get k8s ApiClient:" + e.getMessage());
        }
    }

}

View on GitHub (pinned to 02eac45a1b)

Solutions

1. Fix the k8s_config YAML stored for the cluster (verify with `kubectl --kubeconfig <file> cluster-info`)
2. Check the application log just above the exception for the logged root cause with full stack trace
3. Re-enter cluster credentials via the UI/API after a credential rotation
4. Verify the fabric8 kubernetes-client dependency version is compatible with the target cluster

Example fix

// before: ambiguous rethrow loses stack
throw new RuntimeException("fail to get k8s ApiClient:" + e.getMessage());
// after: preserve cause
throw new RuntimeException("fail to get k8s ApiClient:" + e.getMessage(), e);

// before calling getAndUpdateK8sClient
if (cluster.getK8sConfig() == null || cluster.getK8sConfig().isBlank()) {
    throw new IllegalArgumentException("cluster " + clusterCode + " has empty k8s config");
}
try { new Yaml(new Constructor(io.fabric8.kubernetes.api.model.Config.class)).load(cluster.getK8sConfig()); }
catch (Exception e) { throw new IllegalArgumentException("invalid kubeconfig yaml: " + e.getMessage()); }

boolean hasValidKubeconfig(Cluster c) {
    return c != null && c.getK8sConfig() != null && c.getK8sConfig().contains("clusters:")
        && c.getK8sConfig().contains("server:");
}

try {
    k8sManager.getAndUpdateK8sClient(clusterCode);
} catch (RuntimeException e) {
    if (e.getMessage().contains("fail to get k8s ApiClient")) {
        log.error("K8s client init failed for cluster {}, fix cluster config and retry", clusterCode, e);
        // fall back to default client or abort deployment gracefully
    } else { throw e; }
}

When it happens

Trigger: getAndUpdateK8sClient(clusterCode) is called and getClient(k8sConfig) throws - typically because the cluster's k8s_config holds invalid/empty YAML, an expired/rotated credential, or the fabric8 client cannot be constructed from the config.

Common situations: Cluster config pasted with wrong indentation or unsubstituted placeholders; kubeconfig from an old cluster after migration; malformed base64 certificate data; fabric8 client version incompatibility with the target cluster.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• namespace %s does not exist in k8s cluster, please create na
• ENVIRONMENT_CONFIG_IS_NULL
• K8S_NAMESPACE_EXIST
• CLUSTER_NOT_EXISTS
• K8S_CLIENT_OPS_ERROR

AI-assisted analysis of apache/dolphinscheduler@02eac45a1b (2026-09-06). Data as JSON: /api/errors/2954c909032f1cb0. Report an issue: GitHub.