apache/dolphinscheduler · error · UnsupportedOperationException

There is no userGroup exist cannot create tenant, please cre

Error message

There is no userGroup exist cannot create tenant, please create userGroupFirst

What it means

OSUtils.createUser creates an OS-level tenant user and assigns it to the primary user group returned by getGroup(). If the group lookup returns null/empty (no user group resolvable on this machine), an UnsupportedOperationException is thrown telling the operator to create the group first, because a user cannot be created without a group.

Source

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

     */
    public static synchronized void createUserIfAbsent(String userName) {
        // if not exists this user, then create
        if (!getUserList().contains(userName)) {
            createUser(userName);
        }
    }

    /**
     * create user
     *
     * @param userName user name
     * @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

View on GitHub (pinned to 02eac45a1b)

Solutions

Create the expected user group on the host before starting the worker (e.g. 'groupadd <expected-group>')
Verify the account running DolphinScheduler can read /etc/group and has permission to create users
Disable automatic tenant/user creation and provision OS users manually

Example fix

// before (on the worker host)
# no group exists -> createUser throws
// after
sudo groupadd workers && sudo usermod -aG workers $USER

Defensive patterns

Strategy: validation

Validate before calling

String group = OSUtils.getGroup();
if (StringUtils.isEmpty(group)) {
    throw new IllegalStateException("No user group available; create one before creating tenants");
}

Try / catch

try { OSUtils.createUser(userName); } catch (UnsupportedOperationException e) { log.error("Missing user group: provision the group first", e); }

Prevention

Ensure the expected group exists on every worker host before startup
Run workers on images that include standard user/group tools
Provision OS users manually instead of relying on auto-creation in restricted environments

When it happens

Trigger: Calling createUser / createUserIfAbsent on a machine where getGroup() returns empty — e.g. Linux host with no 'admin'-style group matching the lookup logic, unusual /etc/group, or running under an account whose primary group cannot be determined.

Common situations: Fresh minimal Linux servers or containers (e.g. slim Docker images) lacking expected groups; worker nodes where tenant auto-creation is enabled but the OS has no suitable group; macOS/Windows edge cases.

Related errors

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