apache/dolphinscheduler · error · RuntimeException

namespace %s does not exist in k8s cluster, please create na

Error message

namespace %s does not exist in k8s cluster, please create namespace in k8s cluster first

What it means

Thrown by K8sClientService.upsertNamespaceAndResourceToK8s as a plain RuntimeException when checkNamespaceToK8s finds that the requested namespace does not exist in the target Kubernetes cluster. DolphinScheduler requires the namespace to pre-exist in the cluster before it will upsert namespace resources (service account/label) for it.

Source

Thrown at dolphinscheduler-api/src/main/java/org/apache/dolphinscheduler/api/k8s/K8sClientService.java:41

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Component;

import io.fabric8.kubernetes.api.model.Namespace;
import io.fabric8.kubernetes.api.model.NamespaceList;

/**
 * Encapsulates all client-related operations, not involving the db
 */
@Component
public class K8sClientService {

    @Autowired
    private K8sManager k8sManager;

    public void upsertNamespaceAndResourceToK8s(K8sNamespace k8sNamespace) {
        if (!checkNamespaceToK8s(k8sNamespace.getNamespace(), k8sNamespace.getClusterCode())) {
            throw new RuntimeException(String.format(
                    "namespace %s does not exist in k8s cluster, please create namespace in k8s cluster first",
                    k8sNamespace.getNamespace()));
        }
    }

    private Optional<Namespace> getNamespaceFromK8s(String name, Long clusterCode) {
        NamespaceList listNamespace =
                k8sManager.getK8sClient(clusterCode).namespaces().list();

        Optional<Namespace> list =
                listNamespace.getItems().stream()
                        .filter((Namespace namespace) -> namespace.getMetadata().getName().equals(name))
                        .findFirst();

        return list;
    }

    private boolean checkNamespaceToK8s(String name, Long clusterCode) {

View on GitHub (pinned to 02eac45a1b)

Solutions

Create the namespace in the target Kubernetes cluster first: kubectl create namespace <name> against the cluster matching clusterCode
Verify the clusterCode maps to the cluster where the namespace actually exists
Check the cluster's kubeconfig/credentials in DolphinScheduler are valid and have RBAC to read namespaces
Re-check the namespace name for typos/case differences

Example fix

// before
k8sClientService.upsertNamespaceAndResourceToK8s(k8sNamespace);
// after
Runtime.exec-less shell step:
// kubectl config use-context <cluster-for-clusterCode>
// kubectl create namespace <k8sNamespace.getNamespace()>
// then call upsertNamespaceAndResourceToK8s(k8sNamespace);

Defensive patterns

Strategy: validation

Validate before calling

boolean exists = k8sClient.namespaces()
    .withName(k8sNamespace.getNamespace()) != null
    && k8sClient.namespaces().withName(k8sNamespace.getNamespace()).get() != null;
if (!exists) {
    throw new IllegalStateException("Create namespace " + k8sNamespace.getNamespace() + " in k8s first");
}

Prevention

Create namespaces in the cluster before registering them in DolphinScheduler
Confirm clusterCode points to the cluster where the namespace lives
Validate kubeconfig/credentials and RBAC read access to namespaces
Check namespace name spelling and case before calling

When it happens

Trigger: Calling upsertNamespaceAndResourceToK8s with a K8sNamespace whose namespace name cannot be found in the cluster identified by clusterCode — getNamespaceFromK8s returns empty for that name in that cluster context.

Common situations: Typo in namespace name; namespace created in a different cluster than the one registered by clusterCode; kubeconfig/credentials for the cluster wrong so the lookup fails; namespace deleted after being registered in DolphinScheduler UI; using a namespace that exists in k8s but was never created by an admin with proper RBAC.

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/670ce79e9c3a3f84. Report an issue: GitHub.