apache/dolphinscheduler · error · RuntimeException

Create tenant: {} failed

Error message

Create tenant: {} failed

What it means

OSUtils.createUser wraps the whole tenant-creation flow (group lookup, OS-specific user creation commands) in a try/catch and rethrows any failure as a RuntimeException("Create tenant: {} failed", e). It indicates an underlying OS command (useradd/usermod/user creation) or lookup failed while provisioning the tenant user.

Source

Thrown at dolphinscheduler-common/src/main/java/org/apache/dolphinscheduler/common/utils/OSUtils.java:215

     * @return true if creation was successful, otherwise false
     */
    public static void createUser(String userName) {
        try {
            String userGroup = getGroup();
            if (StringUtils.isEmpty(userGroup)) {
                throw new UnsupportedOperationException(
                        "There is no userGroup exist cannot create tenant, please create userGroupFirst");
            }
            if (SystemUtils.IS_OS_MAC) {
                createMacUser(userName, userGroup);
            } else if (SystemUtils.IS_OS_WINDOWS) {
                createWindowsUser(userName, userGroup);
            } else {
                createLinuxUser(userName, userGroup);
            }
            log.info("Create tenant {} under userGroup: {} success", userName, userGroup);
        } catch (Exception e) {
            throw new RuntimeException("Create tenant: {} failed", e);
        }

    }

    /**
     * create linux user
     *
     * @param userName  user name
     * @param userGroup user group
     * @throws IOException in case of an I/O error
     */
    private static void createLinuxUser(String userName, String userGroup) throws IOException {
        log.info("create linux os user: {}", userName);
        String cmd = String.format("sudo useradd -m -g %s %s", userGroup, userName);
        log.info("execute cmd: {}", cmd);
        exeCmd(cmd);
    }

View on GitHub (pinned to 02eac45a1b)

Solutions

1. Inspect the cause chain of the RuntimeException to find the real failure (the wrapped exception 'e')
2. Run the worker with sufficient privileges (root/sudo) to execute user creation commands, and ensure useradd/groupadd exist in the image
3. Pre-create the tenant OS user manually, or verify the group exists per error 516 before retrying

Example fix

// before: container without useradd
FROM eclipse-temurin:17-jre-alpine
// after
FROM eclipse-temurin:17-jre-jammy  # includes useradd; also run worker as root or with sudo rights

// pre-checks
if (StringUtils.isEmpty(OSUtils.getGroup())) throw new IllegalStateException("group missing");
boolean privileged = checkCanRunUseradd(); // worker has permission to create users

try { OSUtils.createUser(userName); } catch (RuntimeException e) { log.error("Tenant creation failed: {}", e.getCause(), e); /* remediate: fix privileges/group, then retry */ }

When it happens

Trigger: Any exception inside createUser: missing user group, the process lacking root/sudo privileges to run useradd, createLinuxUser/createMacUser/createWindowsUser command failing, or user already existing in an unhandled way.

Common situations: Worker not running as a privileged user able to create accounts; 'useradd' not installed in the container; group missing (see 516); tenant OS user already exists from a previous run.

Understand the failure class

Background: "API request failed": what wrapped HTTP errors from external APIs mean and how to find the real cause — this error's family across 29 libraries.

Related errors

• There is no userGroup exist cannot create tenant, please cre
• TenantCode: %s doesn't exist
• Can not create or update workflow for user who not related t
• java.lang.CloneNotSupportedException
• DELETE_TENANT_BY_ID_FAIL_TENANTS

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