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.

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)

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());
Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

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

Prevention

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

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