alibaba/nacos · warning · IllegalArgumentException

username is blank

Error message

username is blank

What it means

validateUserCredentials() is the guard invoked at the start of createUser(); a blank/null username is rejected before any remote call is made. StringUtils.isBlank treats empty string and whitespace-only as blank, so leading/trailing spaces alone also fail.

Source

Thrown at plugin-default-impl/nacos-default-auth-plugin/src/main/java/com/alibaba/nacos/plugin/auth/impl/users/AbstractCachedUserService.java:80

    
    /**
     * Reject reserved system usernames from being created or deleted.
     *
     * @param username the username to check
     */
    protected void rejectReservedUsername(String username) {
        if (AuthConstants.ANONYMOUS_USER.equals(username)) {
            throw new IllegalArgumentException(
                "username '" + AuthConstants.ANONYMOUS_USER + "' is reserved by the system");
        }
    }
    
    /**
     * [ISSUE #13625] check username and password is blank.
     */
    protected void validateUserCredentials(String username, String password) {
        if (StringUtils.isBlank(username)) {
            throw new IllegalArgumentException("username is blank");
        }
        rejectReservedUsername(username);
        if (StringUtils.isBlank(password)) {
            throw new IllegalArgumentException("password is blank");
        }
    }
}

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Validate the username is non-blank on the client before submitting.
2. Trim the input and reject empty values in your service layer.
3. Return a clear 400 to the caller instead of letting the plugin throw.

Example fix

// before
userService.createUser(username, password, true); // username == "" -> IllegalArgumentException

// after
if (username == null || username.trim().isEmpty()) {
    return Result.failure(400, "username is required");
}
userService.createUser(username.trim(), password, true);

import com.alibaba.nacos.common.utils.StringUtils;

if (StringUtils.isBlank(username)) {
    throw new IllegalArgumentException("username is blank");
}
String clean = username.trim();
if (clean.isEmpty()) {
    throw new IllegalArgumentException("username is blank after trim");
}

try {
    userService.createUser(username, password, false);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("username is blank")) {
        return Result.failure(400, "username is required");
    }
    throw e;
}

When it happens

Trigger: Calling createUser(username, password, encode) with an empty or whitespace-only username — typically from a form field that was not required-validated on the client, or a null passed by an API client.

Common situations: Frontend missing a required-field check; API client sending null username; copy-paste introducing whitespace; automated script with an empty row.

Related errors

• password is blank
• user '{username}' not found!
• username '__nacos_anonymous__' is reserved by the system
• Request parameter `agentSpecCard` should not be null or empt
• Required parameter `agentSpecCard.name` is not present.

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