apache/dolphinscheduler · error · TaskException

TenantCode: %s doesn't exist

Error message

TenantCode: %s doesn't exist

What it means

getOrCreateActualTenant throws TaskException when the tenant (OS user) does not exist on the worker host after any auto-creation attempt. tenantExists(tenantCode) returned false, so the task cannot be executed under that Linux user.

Source

Thrown at dolphinscheduler-worker/src/main/java/org/apache/dolphinscheduler/server/worker/utils/TenantUtils.java:74

        String tenantCode = taskExecutionContext.getTenantCode();
        if (isDefaultTenant(tenantCode)) {
            if (tenantConfig.isDefaultTenantEnabled()) {
                log.info("Current tenant is default tenant, will use bootstrap user: {} to execute the task",
                        getBootstrapTenant());
                return getBootstrapTenant();
            } else {
                throw new TaskException(
                        "The tenantCode is " + tenantCode + ", please enable TenantConfig#isDefaultTenantEnabled");
            }
        }

        if (tenantConfig.isAutoCreateTenantEnabled()) {
            OSUtils.createUserIfAbsent(tenantCode);
        }

        if (!tenantExists(tenantCode)) {
            throw new TaskException(String.format("TenantCode: %s doesn't exist", tenantCode));
        }
        return tenantCode;
    }

    public static boolean isDefaultTenant(String tenantCode) {
        return TenantConstants.DEFAULT_TENANT_CODE.equals(tenantCode);
    }

    public static String getBootstrapTenant() {
        return TenantConstants.BOOTSTRAP_SYSTEM_USER;
    }

    public static boolean isBootstrapTenant(String tenantCode) {
        return TenantConstants.BOOTSTRAP_SYSTEM_USER.equals(tenantCode);
    }

    public static boolean tenantExists(String tenantCode) {
        return OSUtils.getUserList().contains(tenantCode);

View on GitHub (pinned to 02eac45a1b)

Solutions

1. Create the OS user on every worker host: useradd <tenantCode>.
2. Enable tenant-config.auto-create-tenant-enabled=true so workers create the user if absent (requires sudo rights for the worker user).
3. Ensure the worker process has permission to run useradd (sudoers entry) when auto-creation is on.
4. Verify the tenant name matches a valid Linux username (no invalid characters).

Example fix

// before
sudo useradd -m ds_tenant -s /bin/bash  # run on ALL worker nodes
// or enable auto-create
# tenant-config.auto-create-tenant-enabled=true

// on each worker before scheduling
import pwd
try:
    pwd.getpwnam(tenant_code)
except KeyError:
    raise SystemExit(f"OS user {tenant_code} missing on worker")

try { runTask(tenantCode); } catch (TaskException e) { if (e.getMessage().contains("doesn't exist")) createUserOnWorkers(tenantCode); }

When it happens

Trigger: Task has a non-default tenantCode; isAutoCreateTenantEnabled is false (or user creation failed) and tenantExists(tenantCode) is false, i.e. no such Linux user on the worker machine.

Common situations: Tenant created in the UI but the matching Linux user was never created on worker nodes; auto-create disabled; user creation failed due to missing sudo/useradd permissions; multi-node cluster where only some workers have the user.

Understand the failure class

Background: "User not found", "Invalid user", and "does not exist": what missing-user lookup errors mean across Rocket.Chat, LiteLLM, Phabricator, rustfs, and pnpm — this error's family across 10 libraries.

Related errors

• There is no userGroup exist cannot create tenant, please cre
• Create tenant: {} failed
• The tenantCode is
• Can not create or update workflow for user who not related t
• DELETE_TENANT_BY_ID_FAIL_TENANTS

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