{"record":{"id":"7f7d0be0f520b26f","repo":"apache/dolphinscheduler","slug":"cluster-not-exists","errorCode":"CLUSTER_NOT_EXISTS","errorMessage":"CLUSTER_NOT_EXISTS","messagePattern":"CLUSTER_NOT_EXISTS","errorType":"error_code","errorClass":"ServiceException","httpStatus":null,"severity":"error","filePath":"dolphinscheduler-api/src/main/java/org/apache/dolphinscheduler/api/service/impl/K8SNamespaceServiceImpl.java","lineNumber":133,"sourceCode":"        if (StringUtils.isEmpty(namespace)) {\n            log.warn(\"Parameter namespace is empty.\");\n            throw new ServiceException(Status.REQUEST_PARAMS_NOT_VALID_ERROR, Constants.NAMESPACE);\n        }\n\n        if (clusterCode == null) {\n            log.warn(\"Parameter clusterCode is null.\");\n            throw new ServiceException(Status.REQUEST_PARAMS_NOT_VALID_ERROR, Constants.CLUSTER);\n        }\n\n        if (checkNamespaceExistInDb(namespace, clusterCode)) {\n            log.warn(\"K8S namespace already exists.\");\n            throw new ServiceException(Status.K8S_NAMESPACE_EXIST, namespace, clusterCode);\n        }\n\n        Cluster cluster = clusterDao.queryByClusterCode(clusterCode);\n        if (cluster == null) {\n            log.error(\"Cluster does not exist, clusterCode:{}\", clusterCode);\n            throw new ServiceException(Status.CLUSTER_NOT_EXISTS, namespace, clusterCode);\n        }\n\n        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);","sourceCodeStart":115,"sourceCodeEnd":151,"githubUrl":"https://github.com/apache/dolphinscheduler/blob/02eac45a1b6676e639fcbfb4be2243de5771b05d/dolphinscheduler-api/src/main/java/org/apache/dolphinscheduler/api/service/impl/K8SNamespaceServiceImpl.java#L115-L151","documentation":"CLUSTER_NOT_EXISTS is thrown by K8sNamespaceServiceImpl.registerK8sNamespace when clusterDao.queryByClusterCode(clusterCode) returns null. The namespace references a cluster code that has no matching row in the cluster registry (t_ds_cluster), so registration cannot proceed. The exception is constructed with the namespace and clusterCode as message arguments.","triggerScenarios":"Registering a K8s namespace with a clusterCode that was never defined via the cluster-management API; passing a stale or deleted clusterCode; passing the cluster NAME instead of its numeric code; a client that desynchronized cluster codes from a different environment's database.","commonSituations":"Deploying across environments where cluster codes differ between dev and prod databases; cluster was deleted while namespace templates still reference it; copying API payloads between installations; confusing cluster name/label with the generated cluster code.","solutions":["Look up the correct clusterCode via the cluster list API (or SELECT code FROM t_ds_cluster WHERE name=...) and use it in the request.","Create/register the target cluster first through the cluster-management endpoints, then retry namespace registration.","Fix environment config/scripts that hard-code a clusterCode from another environment.","Verify the cluster was not deleted; re-add it with a new code if so."],"exampleFix":"// before\nservice.registerK8sNamespace(loginUser, \"prod-ns\", 1234567890L); // stale hard-coded code\n\n// after\nCluster cluster = clusterDao.queryByClusterName(\"prod-cluster\");\nservice.registerK8sNamespace(loginUser, \"prod-ns\", cluster.getCode());","handlingStrategy":"validation","validationCode":"// Resolve and validate clusterCode before registering\nCluster cluster = clusterDao.queryByClusterCode(clusterCode);\nif (cluster == null) {\n    throw new IllegalArgumentException(\"unknown clusterCode: \" + clusterCode);\n}","typeGuard":null,"tryCatchPattern":"try {\n    service.registerK8sNamespace(loginUser, namespace, clusterCode);\n} catch (ServiceException e) {\n    if (Status.CLUSTER_NOT_EXISTS.getCode() == e.getCode()) {\n        log.error(\"cluster {} not found; fetch valid code from cluster list API\", e.getArgs());\n    }\n    throw e;\n}","preventionTips":["Always resolve clusterCode from the cluster list API rather than hard-coding numbers.","Keep environment-specific cluster codes in per-environment configuration, never copy between envs.","Watch for cluster deletions that orphan namespace registrations."],"tags":["cluster","invalid-reference","kubernetes"],"backgroundTag":"resource-not-found","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"}