alibaba/nacos · error · IllegalArgumentException

user ' + username + ' already exist!

Error message

user ' + username + ' already exist!

What it means

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.

Source

Thrown at plugin-default-impl/nacos-default-auth-plugin/src/main/java/com/alibaba/nacos/plugin/auth/impl/controller/v3/UserControllerV3.java:112

    }
    
    /**
     * Create a new user.
     *
     * @param username username
     * @param password password
     * @return ok if create succeed
     * @throws IllegalArgumentException if user already exist
     * @since 1.2.0
     */
    @Secured(resource = AuthConstants.CONSOLE_RESOURCE_NAME_PREFIX + "users",
        action = ActionTypes.WRITE, apiType = ApiType.ADMIN_API)
    @Since("3.0.0")
    @PostMapping
    public Result<String> createUser(@RequestParam String username, @RequestParam String password) {
        User user = userDetailsService.getUser(username);
        if (user != null) {
            throw new IllegalArgumentException("user '" + username + "' already exist!");
        }
        userDetailsService.createUser(username, password);
        return Result.success("create user ok!");
    }
    
    /**
     * Create a admin user only not exist admin user can use.
     */
    @Since("3.0.0")
    @PostMapping("/admin")
    public Result<User> createAdminUser(@RequestParam(required = false) String password) {
        
        if (StringUtils.isBlank(password)) {
            password = PasswordGeneratorUtil.generateRandomPassword();
        }
        
        if (AuthSystemTypes.NACOS.name()
            .equalsIgnoreCase(getServerAuthConfig().getNacosAuthSystemType())) {

View on GitHub (pinned to 9b989acdf1)

Solutions

1. GET the user first and skip creation if it already exists (idempotent bootstrap).
2. Catch IllegalArgumentException at the controller/edge and return a 409-style message instead of a 500.
3. For initial admin bootstrap use the dedicated POST /admin endpoint which only runs when no admin exists.

Example fix

// before
userDetailsService.createUser(username, password); // may throw on retry

// after: check-then-create guard
if (userDetailsService.getUser(username) == null) {
    userDetailsService.createUser(username, password);
}

if (userDetailsService.getUser(username) != null) {
    // already exists; skip creation (idempotent)
    return;
}

boolean userExists(NacosUserService s, String u) { return s.getUser(u) != null; }

try {
    userDetailsService.createUser(username, password);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("already exist")) { /* idempotent success */ }
    else throw e;
}

When it happens

Trigger: 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.

Common situations: Re-running a bootstrap script that creates initial users; double-clicking submit in the console; migrating users without checking existence first.

Related errors

• cannot delete admin: + username
• user + username + not exist!
• Duplicate CallInterface protocol: {callInterface.getProtocol
• user '{username}' already bound to the role '{role}'!
• role 'ROLE_ADMIN' already exist !

AI-assisted analysis of alibaba/nacos@9b989acdf1 (2026-08-14). Data as JSON: /api/errors/7f9791f41176bc87. Report an issue: GitHub.