{"record":{"id":"18e5c75e61c42031","repo":"apache/dolphinscheduler","slug":"k8s-client-ops-error","errorCode":"K8S_CLIENT_OPS_ERROR","errorMessage":"K8S_CLIENT_OPS_ERROR","messagePattern":"K8S_CLIENT_OPS_ERROR","errorType":"error_code","errorClass":"ServiceException","httpStatus":null,"severity":"error","filePath":"dolphinscheduler-api/src/main/java/org/apache/dolphinscheduler/api/service/impl/K8SNamespaceServiceImpl.java","lineNumber":154,"sourceCode":"        long code = CodeGenerateUtils.genCode();\n        cluster.setCode(code);\n\n        K8sNamespace k8sNamespaceObj = new K8sNamespace();\n        Date now = new Date();\n\n        k8sNamespaceObj.setCode(code);\n        k8sNamespaceObj.setNamespace(namespace);\n        k8sNamespaceObj.setClusterCode(clusterCode);\n        k8sNamespaceObj.setUserId(loginUser.getId());\n        k8sNamespaceObj.setCreateTime(now);\n        k8sNamespaceObj.setUpdateTime(now);\n\n        if (!Constants.K8S_LOCAL_TEST_CLUSTER_CODE.equals(k8sNamespaceObj.getClusterCode())) {\n            try {\n                k8sClientService.upsertNamespaceAndResourceToK8s(k8sNamespaceObj);\n            } catch (Exception e) {\n                log.error(\"Namespace create to k8s error\", e);\n                throw new ServiceException(Status.K8S_CLIENT_OPS_ERROR, e.getMessage());\n            }\n        }\n\n        k8sNamespaceDao.insert(k8sNamespaceObj);\n        log.info(\"K8s namespace create complete, namespace:{}.\", k8sNamespaceObj.getNamespace());\n        return k8sNamespaceObj;\n    }\n\n    /**\n     * verify namespace and k8s\n     *\n     * @param namespace   namespace\n     * @param clusterCode cluster code\n     * @return true if the k8s and namespace not exists, otherwise return false\n     */\n    @Override\n    public Result<Object> verifyNamespaceK8s(String namespace, Long clusterCode) {\n        Result<Object> result = new Result<>();","sourceCodeStart":136,"sourceCodeEnd":172,"githubUrl":"https://github.com/apache/dolphinscheduler/blob/02eac45a1b6676e639fcbfb4be2243de5771b05d/dolphinscheduler-api/src/main/java/org/apache/dolphinscheduler/api/service/impl/K8SNamespaceServiceImpl.java#L136-L172","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the wrapped message from the exception/log ('Namespace create to k8s error') and fix the root Kubernetes API error it reports.","Verify connectivity and credentials to the cluster API server from the API server host (kubectl get ns with the same kubeconfig).","Check RBAC: the service account must have permission to create namespaces and configmaps in the target cluster.","Ensure the namespace name is DNS-1123 compliant (lowercase alphanumerics and '-').","If you only want DB registration without touching a real cluster, use the local test cluster code (K8S_LOCAL_TEST_CLUSTER_CODE)."],"exampleFix":"// before\nservice.registerK8sNamespace(loginUser, \"Prod_NS\", clusterCode); // invalid k8s name -> client ops error\n\n// after\nString ns = \"prod-ns\"; // DNS-1123 compliant\nservice.registerK8sNamespace(loginUser, ns, clusterCode);","handlingStrategy":"try-catch","validationCode":"// Pre-validate namespace name against k8s DNS-1123 rules\nif (!namespace.matches(\"^[a-z0-9]([-a-z0-9]*[a-z0-9])?$\")) {\n    throw new IllegalArgumentException(\"invalid k8s namespace name: \" + namespace);\n}","typeGuard":null,"tryCatchPattern":"try {\n    service.registerK8sNamespace(loginUser, namespace, clusterCode);\n} catch (ServiceException e) {\n    if (Status.K8S_CLIENT_OPS_ERROR.getCode() == e.getCode()) {\n        log.error(\"k8s API call failed: {}\", e.getMessage()); // underlying kube error\n    }\n    throw e;\n}","preventionTips":["Verify kubeconfig/connectivity to the cluster from the API server host before registering.","Grant the service account RBAC to create namespaces and configmaps.","Use lowercase DNS-1123-compliant namespace names.","Use the local test cluster code in dev so no real k8s call is made."],"tags":["kubernetes","api-server","network"],"backgroundTag":"api-request-failed","analyzedSha":"02eac45a1b6676e639fcbfb4be2243de5771b05d","analyzedAt":"2026-09-06T17:43:00.555Z","contentChangedAt":"2026-09-06T17:43:00.555Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}