{"record":{"id":"7f9791f41176bc87","repo":"alibaba/nacos","slug":"user-username-already-exist","errorCode":null,"errorMessage":"user ' + username + ' already exist!","messagePattern":"user ' \\+ username \\+ ' already exist!","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"plugin-default-impl/nacos-default-auth-plugin/src/main/java/com/alibaba/nacos/plugin/auth/impl/controller/v3/UserControllerV3.java","lineNumber":112,"sourceCode":"    }\n    \n    /**\n     * Create a new user.\n     *\n     * @param username username\n     * @param password password\n     * @return ok if create succeed\n     * @throws IllegalArgumentException if user already exist\n     * @since 1.2.0\n     */\n    @Secured(resource = AuthConstants.CONSOLE_RESOURCE_NAME_PREFIX + \"users\",\n        action = ActionTypes.WRITE, apiType = ApiType.ADMIN_API)\n    @Since(\"3.0.0\")\n    @PostMapping\n    public Result<String> createUser(@RequestParam String username, @RequestParam String password) {\n        User user = userDetailsService.getUser(username);\n        if (user != null) {\n            throw new IllegalArgumentException(\"user '\" + username + \"' already exist!\");\n        }\n        userDetailsService.createUser(username, password);\n        return Result.success(\"create user ok!\");\n    }\n    \n    /**\n     * Create a admin user only not exist admin user can use.\n     */\n    @Since(\"3.0.0\")\n    @PostMapping(\"/admin\")\n    public Result<User> createAdminUser(@RequestParam(required = false) String password) {\n        \n        if (StringUtils.isBlank(password)) {\n            password = PasswordGeneratorUtil.generateRandomPassword();\n        }\n        \n        if (AuthSystemTypes.NACOS.name()\n            .equalsIgnoreCase(getServerAuthConfig().getNacosAuthSystemType())) {","sourceCodeStart":94,"sourceCodeEnd":130,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/plugin-default-impl/nacos-default-auth-plugin/src/main/java/com/alibaba/nacos/plugin/auth/impl/controller/v3/UserControllerV3.java#L94-L130","documentation":"Thrown by UserControllerV3.createUser as IllegalArgumentException when creating a user whose username already exists. The POST /v3/admin/.../users (or console-aliased) endpoint checks userDetailsService.getUser(username) and rejects duplicates before creation.","triggerScenarios":"POST to the v3 user-create endpoint with a username that already resolves to a stored User. Repeat submission, retry after a partial success, or an idempotency gap in the client.","commonSituations":"Re-running a bootstrap script that creates initial users; double-clicking submit in the console; migrating users without checking existence first.","solutions":["GET the user first and skip creation if it already exists (idempotent bootstrap).","Catch IllegalArgumentException at the controller/edge and return a 409-style message instead of a 500.","For initial admin bootstrap use the dedicated POST /admin endpoint which only runs when no admin exists."],"exampleFix":"// before\nuserDetailsService.createUser(username, password); // may throw on retry\n\n// after: check-then-create guard\nif (userDetailsService.getUser(username) == null) {\n    userDetailsService.createUser(username, password);\n}","handlingStrategy":"validation","validationCode":"if (userDetailsService.getUser(username) != null) {\n    // already exists; skip creation (idempotent)\n    return;\n}","typeGuard":"boolean userExists(NacosUserService s, String u) { return s.getUser(u) != null; }","tryCatchPattern":"try {\n    userDetailsService.createUser(username, password);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().contains(\"already exist\")) { /* idempotent success */ }\n    else throw e;\n}","preventionTips":["Make user-bootstrap scripts idempotent: check existence before create.","Surface duplicate-user as 409 Conflict at the API edge.","Use the /admin endpoint only for the initial admin."],"tags":["auth","user","duplicate","illegal-argument"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}