apache/dolphinscheduler · error · UnsupportedOperationException

There is no userGroup exist cannot create tenant, please…

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.

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.

Appendix: 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)