apache/dolphinscheduler · error · ServiceException

CLUSTER_NOT_EXISTS

CLUSTER_NOT_EXISTS

Error message

CLUSTER_NOT_EXISTS

What it means

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.

Solutions

1. 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.
2. Create/register the target cluster first through the cluster-management endpoints, then retry namespace registration.
3. Fix environment config/scripts that hard-code a clusterCode from another environment.
4. Verify the cluster was not deleted; re-add it with a new code if so.

Example fix

// before
service.registerK8sNamespace(loginUser, "prod-ns", 1234567890L); // stale hard-coded code

// after
Cluster cluster = clusterDao.queryByClusterName("prod-cluster");
service.registerK8sNamespace(loginUser, "prod-ns", cluster.getCode());

// Resolve and validate clusterCode before registering
Cluster cluster = clusterDao.queryByClusterCode(clusterCode);
if (cluster == null) {
    throw new IllegalArgumentException("unknown clusterCode: " + clusterCode);
}

try {
    service.registerK8sNamespace(loginUser, namespace, clusterCode);
} catch (ServiceException e) {
    if (Status.CLUSTER_NOT_EXISTS.getCode() == e.getCode()) {
        log.error("cluster {} not found; fetch valid code from cluster list API", e.getArgs());
    }
    throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• 120022
• 120023
• 120025
• 120033
• 120034

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

Appendix: source

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

        if (StringUtils.isEmpty(namespace)) {
            log.warn("Parameter namespace is empty.");
            throw new ServiceException(Status.REQUEST_PARAMS_NOT_VALID_ERROR, Constants.NAMESPACE);
        }

        if (clusterCode == null) {
            log.warn("Parameter clusterCode is null.");
            throw new ServiceException(Status.REQUEST_PARAMS_NOT_VALID_ERROR, Constants.CLUSTER);
        }

        if (checkNamespaceExistInDb(namespace, clusterCode)) {
            log.warn("K8S namespace already exists.");
            throw new ServiceException(Status.K8S_NAMESPACE_EXIST, namespace, clusterCode);
        }

        Cluster cluster = clusterDao.queryByClusterCode(clusterCode);
        if (cluster == null) {
            log.error("Cluster does not exist, clusterCode:{}", clusterCode);
            throw new ServiceException(Status.CLUSTER_NOT_EXISTS, namespace, clusterCode);
        }

        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);

View on GitHub (pinned to 02eac45a1b)