apache/dolphinscheduler · error · ServiceException

K8S_CLIENT_OPS_ERROR

K8S_CLIENT_OPS_ERROR

Error message

K8S_CLIENT_OPS_ERROR

What it means

K8S_CLIENT_OPS_ERROR is thrown by K8sNamespaceServiceImpl.registerK8sNamespace when k8sClientService.upsertNamespaceAndResourceToK8s fails to create the namespace (and its associated resource, e.g. configmap) on the actual Kubernetes cluster. The original exception message is wrapped into a ServiceException. This error indicates the Kubernetes API call itself failed, not the DolphinScheduler database layer.

Source

Thrown at dolphinscheduler-api/src/main/java/org/apache/dolphinscheduler/api/service/impl/K8SNamespaceServiceImpl.java:154

        long code = CodeGenerateUtils.genCode();
        cluster.setCode(code);

        K8sNamespace k8sNamespaceObj = new K8sNamespace();
        Date now = new Date();

        k8sNamespaceObj.setCode(code);
        k8sNamespaceObj.setNamespace(namespace);
        k8sNamespaceObj.setClusterCode(clusterCode);
        k8sNamespaceObj.setUserId(loginUser.getId());
        k8sNamespaceObj.setCreateTime(now);
        k8sNamespaceObj.setUpdateTime(now);

        if (!Constants.K8S_LOCAL_TEST_CLUSTER_CODE.equals(k8sNamespaceObj.getClusterCode())) {
            try {
                k8sClientService.upsertNamespaceAndResourceToK8s(k8sNamespaceObj);
            } catch (Exception e) {
                log.error("Namespace create to k8s error", e);
                throw new ServiceException(Status.K8S_CLIENT_OPS_ERROR, e.getMessage());
            }
        }

        k8sNamespaceDao.insert(k8sNamespaceObj);
        log.info("K8s namespace create complete, namespace:{}.", k8sNamespaceObj.getNamespace());
        return k8sNamespaceObj;
    }

    /**
     * verify namespace and k8s
     *
     * @param namespace   namespace
     * @param clusterCode cluster code
     * @return true if the k8s and namespace not exists, otherwise return false
     */
    @Override
    public Result<Object> verifyNamespaceK8s(String namespace, Long clusterCode) {
        Result<Object> result = new Result<>();

View on GitHub (pinned to 02eac45a1b)

Solutions

1. Read the wrapped message from the exception/log ('Namespace create to k8s error') and fix the root Kubernetes API error it reports.
2. Verify connectivity and credentials to the cluster API server from the API server host (kubectl get ns with the same kubeconfig).
3. Check RBAC: the service account must have permission to create namespaces and configmaps in the target cluster.
4. Ensure the namespace name is DNS-1123 compliant (lowercase alphanumerics and '-').
5. If you only want DB registration without touching a real cluster, use the local test cluster code (K8S_LOCAL_TEST_CLUSTER_CODE).

Example fix

// before
service.registerK8sNamespace(loginUser, "Prod_NS", clusterCode); // invalid k8s name -> client ops error

// after
String ns = "prod-ns"; // DNS-1123 compliant
service.registerK8sNamespace(loginUser, ns, clusterCode);

// Pre-validate namespace name against k8s DNS-1123 rules
if (!namespace.matches("^[a-z0-9]([-a-z0-9]*[a-z0-9])?$")) {
    throw new IllegalArgumentException("invalid k8s namespace name: " + namespace);
}

try {
    service.registerK8sNamespace(loginUser, namespace, clusterCode);
} catch (ServiceException e) {
    if (Status.K8S_CLIENT_OPS_ERROR.getCode() == e.getCode()) {
        log.error("k8s API call failed: {}", e.getMessage()); // underlying kube error
    }
    throw e;
}

When it happens

Trigger: Any non-local cluster registration (clusterCode != 'test' / K8S_LOCAL_TEST_CLUSTER_CODE) where the k8s client cannot upsert the namespace: unreachable API server, bad kubeconfig, RBAC denial, invalid namespace name (e.g. uppercase or invalid DNS label), quota/limit issues.

Common situations: Misconfigured kubeconfig for the worker/api server; cluster API server unreachable from the DolphinScheduler network; service account lacking namespace-create RBAC permissions; namespace names violating Kubernetes DNS-1123 rules (uppercase letters, underscores); expired client credentials.

Understand the failure class

Background: "API request failed": what wrapped HTTP errors from external APIs mean and how to find the real cause — this error's family across 29 libraries.

Related errors

• WorkflowInstance: %s pause failed
• WorkflowInstance: %s stop failed
• namespace %s does not exist in k8s cluster, please create na
• fail to get k8s ApiClient:%s
• OIDC_TOKEN_EXCHANGE_FAILED

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