apache/dolphinscheduler · error · RuntimeException

Can not create or update workflow for user who not related t

Error message

Can not create or update workflow for user who not related to any tenant.

What it means

PythonGateway.createOrUpdateWorkflow (the PyDolphinScheduler gateway) looks up the caller by userName; if the account exists but has no tenant bound (user.getTenantCode() == null) it refuses to create or update the workflow with a RuntimeException, because submitted workflows need a tenant under which tasks run.

Source

Thrown at dolphinscheduler-api/src/main/java/org/apache/dolphinscheduler/api/python/PythonGateway.java:247

    public Long createOrUpdateWorkflow(String userName,
                                       String projectName,
                                       String name,
                                       String description,
                                       String globalParams,
                                       String schedule,
                                       boolean onlineSchedule,
                                       String warningType,
                                       int warningGroupId,
                                       int timeout,
                                       String workerGroup,
                                       int releaseState,
                                       String taskRelationJson,
                                       String taskDefinitionJson,
                                       String otherParamsJson,
                                       String executionType) {
        User user = usersService.queryUser(userName);
        if (user.getTenantCode() == null) {
            throw new RuntimeException("Can not create or update workflow for user who not related to any tenant.");
        }

        Project project = projectDao.queryByName(projectName);
        long projectCode = project.getCode();

        WorkflowDefinition workflowDefinition = getWorkflow(user, projectCode, name);
        WorkflowExecutionTypeEnum executionTypeEnum = WorkflowExecutionTypeEnum.valueOf(executionType);
        long workflowDefinitionCode;
        // create or update workflow
        if (workflowDefinition != null) {
            workflowDefinitionCode = workflowDefinition.getCode();
            // make sure workflow offline which could edit
            workflowDefinitionService.offlineWorkflowDefinition(user, projectCode, workflowDefinitionCode);
            workflowDefinitionService.updateWorkflowDefinition(user, projectCode, name,
                    workflowDefinitionCode, description, globalParams,
                    null, timeout, taskRelationJson, taskDefinitionJson,
                    executionTypeEnum);
        } else {

View on GitHub (pinned to 02eac45a1b)

Solutions

Assign a tenant to the user (UI: Security -> User Management -> edit user -> choose Tenant) or via the user-update API with a tenantCode
Retry the pydolphinscheduler submission after binding the tenant
If the user is missing entirely, create it with createUserIfNotExists including tenantCode

Example fix

// before
User user = usersService.queryUser(userName);
if (user.getTenantCode() == null) { ... }
// after: check user presence AND tenant on caller side
User user = usersService.queryUser(userName);
if (user == null) { throw new RuntimeException("User not found: " + userName); }
if (user.getTenantCode() == null) {
    usersService.grantTenantToUser(user.getId(), defaultTenantId);
}

Defensive patterns

Strategy: validation

Validate before calling

# python client side, before submitting
user = gateway_client.query_user_by_name(user_name)
if user is None:
    user = create_user_if_not_exists(user_name, tenant_code="default")
elif user.get("tenant_code") is None:
    raise ValueError(f"user {user_name} has no tenant; assign one before submitting workflows")

Type guard

// java side
boolean hasTenant(User user) {
    return user != null && user.getTenantCode() != null && !user.getTenantCode().isEmpty();
}

Try / catch

try {
    pythonGateway.createOrUpdateWorkflow(...);
} catch (RuntimeException e) {
    if (e.getMessage().contains("not related to any tenant")) {
        log.warn("bind tenant to user {} and resubmit", userName);
    }
    throw e;
}

Prevention

Always assign a tenant when provisioning gateway/API users
Add tenantCode to user-creation automation scripts
Validate tenant binding in CI before workflow submission
Reject user creation without tenant in custom provisioning flows

When it happens

Trigger: pydolphinscheduler submits a workflow (create or update) using a user account created without a tenant assignment.

Common situations: Admin created the API user but forgot to assign a tenant; tenant was later unbound; scripted user provisioning skipped tenantCode.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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