{"record":{"id":"960c3f987334f8a7","repo":"apache/dolphinscheduler","slug":"create-tenant-failed","errorCode":null,"errorMessage":"Create tenant: {} failed","messagePattern":"Create tenant: (.+?) failed","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"dolphinscheduler-common/src/main/java/org/apache/dolphinscheduler/common/utils/OSUtils.java","lineNumber":215,"sourceCode":"     * @return true if creation was successful, otherwise false\n     */\n    public static void createUser(String userName) {\n        try {\n            String userGroup = getGroup();\n            if (StringUtils.isEmpty(userGroup)) {\n                throw new UnsupportedOperationException(\n                        \"There is no userGroup exist cannot create tenant, please create userGroupFirst\");\n            }\n            if (SystemUtils.IS_OS_MAC) {\n                createMacUser(userName, userGroup);\n            } else if (SystemUtils.IS_OS_WINDOWS) {\n                createWindowsUser(userName, userGroup);\n            } else {\n                createLinuxUser(userName, userGroup);\n            }\n            log.info(\"Create tenant {} under userGroup: {} success\", userName, userGroup);\n        } catch (Exception e) {\n            throw new RuntimeException(\"Create tenant: {} failed\", e);\n        }\n\n    }\n\n    /**\n     * create linux user\n     *\n     * @param userName  user name\n     * @param userGroup user group\n     * @throws IOException in case of an I/O error\n     */\n    private static void createLinuxUser(String userName, String userGroup) throws IOException {\n        log.info(\"create linux os user: {}\", userName);\n        String cmd = String.format(\"sudo useradd -m -g %s %s\", userGroup, userName);\n        log.info(\"execute cmd: {}\", cmd);\n        exeCmd(cmd);\n    }\n","sourceCodeStart":197,"sourceCodeEnd":233,"githubUrl":"https://github.com/apache/dolphinscheduler/blob/02eac45a1b6676e639fcbfb4be2243de5771b05d/dolphinscheduler-common/src/main/java/org/apache/dolphinscheduler/common/utils/OSUtils.java#L197-L233","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Inspect the cause chain of the RuntimeException to find the real failure (the wrapped exception 'e')","Run the worker with sufficient privileges (root/sudo) to execute user creation commands, and ensure useradd/groupadd exist in the image","Pre-create the tenant OS user manually, or verify the group exists per error 516 before retrying"],"exampleFix":"// before: container without useradd\nFROM eclipse-temurin:17-jre-alpine\n// after\nFROM eclipse-temurin:17-jre-jammy  # includes useradd; also run worker as root or with sudo rights","handlingStrategy":"try-catch","validationCode":"// pre-checks\nif (StringUtils.isEmpty(OSUtils.getGroup())) throw new IllegalStateException(\"group missing\");\nboolean privileged = checkCanRunUseradd(); // worker has permission to create users","typeGuard":null,"tryCatchPattern":"try { OSUtils.createUser(userName); } catch (RuntimeException e) { log.error(\"Tenant creation failed: {}\", e.getCause(), e); /* remediate: fix privileges/group, then retry */ }","preventionTips":["Always inspect e.getCause() — the message is just a wrapper","Run the worker with privileges required for useradd/usermod","Pre-create tenant OS users to avoid runtime provisioning failures"],"tags":["os","users","tenant","runtime-exception"],"backgroundTag":"api-request-failed","analyzedSha":"02eac45a1b6676e639fcbfb4be2243de5771b05d","analyzedAt":"2026-09-06T17:43:00.555Z","contentChangedAt":"2026-09-06T17:43:00.555Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}