apache/dolphinscheduler · critical · TaskException

fail to build k8s ApiClient

Error message

fail to build k8s ApiClient

What it means

K8sUtils.buildClient(configYaml) parses the provided kubeconfig YAML with Config.fromKubeconfig and builds a KubernetesClient, wrapping any failure in a TaskException 'fail to build k8s ApiClient'. It fires when the YAML is invalid or the client cannot be constructed from it (bad fields, missing server, expired certs).

Solutions

1. Validate the kubeconfig YAML locally: KUBECONFIG=<file> kubectl cluster-info.
2. Check that the configYaml string is complete, valid YAML, single kubeconfig document.
3. Verify server URL, CA certificate, and token/client-cert fields are present and not placeholders.
4. Regenerate credentials if the token/cert expired, then rebuild the client.
5. Confirm the Fabric8 client dependency version is compatible with your cluster.

Example fix

// before
String configYaml = System.getenv("K8S_CONFIG"); // null or placeholder text
k8sUtils.buildClient(configYaml);
// after
String configYaml = Objects.requireNonNull(System.getenv("K8S_CONFIG"), "K8S_CONFIG not set");
Yaml yaml = new Yaml();
yaml.load(configYaml); // validate parseable before building
k8sUtils.buildClient(configYaml);

if (configYaml == null || configYaml.trim().isEmpty()) {
    throw new IllegalStateException("kubeconfig yaml is empty");
}
new Yaml().load(configYaml); // throws early if not valid YAML

boolean isValidKubeconfig(String yaml) {
    try {
        Object o = new Yaml().load(yaml);
        return o instanceof Map && ((Map<?, ?>) o).containsKey("clusters");
    } catch (Exception e) { return false; }
}

try {
    k8sUtils.buildClient(configYaml);
} catch (TaskException e) {
    throw new IllegalStateException("invalid kubeconfig for K8s tasks", e);
}

When it happens

Trigger: Calling buildClient() with a malformed or empty kubeconfig YAML string, YAML that fails Fabric8 Config parsing, or a config referencing unreachable/invalid server URLs or certificates.

Common situations: K8s config YAML stored in a tenant/resource is truncated or has wrong indentation; a service-account token was rotated; users paste a '~/.kube/config' with multi-document YAML unsupported by parsing; environment variable expansion left placeholders like ${K8S_API_SERVER} unresolved.

Related errors

• 1300006
• CLUSTER_NOT_EXISTS
• Execute k8s task error
• fail to check job:
• fail to create job

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

Appendix: source

Thrown at dolphinscheduler-task-plugin/dolphinscheduler-task-api/src/main/java/org/apache/dolphinscheduler/plugin/task/api/utils/K8sUtils.java:112

                }
            }
            return client.pods().inNamespace(namespace)
                    .withName(podName)
                    .tailingLines(LOG_LINES)
                    .getLog(Boolean.TRUE);
        } catch (Exception e) {
            log.error("fail to getPodLog", e);
            log.error("response bodies : {}", e.getMessage());
        }
        return null;
    }

    public void buildClient(String configYaml) {
        try {
            Config config = Config.fromKubeconfig(configYaml);
            client = new KubernetesClientBuilder().withConfig(config).build();
        } catch (Exception e) {
            throw new TaskException("fail to build k8s ApiClient", e);
        }
    }

}

View on GitHub (pinned to 02eac45a1b)