alibaba/nacos · error · IllegalArgumentException

username is blank

Error message

username is blank

What it means

Thrown by VisibilityGrantRoleHelper.buildUserRoleName when the supplied username is null, empty, or whitespace-only. The method builds a deterministic internal role name (prefix + SHA-256 hex of the username) used to persist visibility grants, so a blank username would produce an ambiguous or insecure role key. It throws IllegalArgumentException to refuse degenerate input early.

Source

Thrown at plugin-default-impl/nacos-default-auth-plugin/src/main/java/com/alibaba/nacos/plugin/auth/impl/visibility/VisibilityGrantRoleHelper.java:77

            return "r";
        }
        if ("w".equals(normalized) || "rw".equals(normalized)) {
            return "rw";
        }
        throw new IllegalArgumentException("unsupported action: " + action);
    }
    
    static boolean matchesRequestedAction(String storedAction, String requestedAction) {
        String normalizedRequested = normalizeStoredAction(requestedAction);
        if ("rw".equals(normalizedRequested)) {
            return "rw".equals(storedAction);
        }
        return "r".equals(storedAction) || "rw".equals(storedAction);
    }
    
    static String buildUserRoleName(String username) {
        if (StringUtils.isBlank(username)) {
            throw new IllegalArgumentException("username is blank");
        }
        // Use a deterministic short SHA-256 prefix so internal role names stay within
        // the existing roles.role varchar(50) limit and do not expose user names.
        return buildUserRoleNamePrefix() + sha256LowerHex(username).substring(0,
            USER_ROLE_HASH_HEX_LENGTH);
    }
    
    static String buildUserRoleNamePrefix() {
        return AuthConstants.VISIBILITY_GRANT_ROLE_PREFIX + USER_ROLE_MARKER;
    }
    
    static boolean isUserGrantRole(String roleName) {
        return StringUtils.isNotBlank(roleName) && roleName.startsWith(buildUserRoleNamePrefix());
    }
    
    static String buildResourceIdentifier(String namespaceId, String resourceType,
        String resourceName) {
        return RESOURCE_IDENTIFIER_PREFIX + normalizeNamespaceId(namespaceId) + "/"

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Validate the username with StringUtils.isBlank(username) before calling buildUserRoleName and reject the request with a clear 400-level error.
2. Trace the call chain upward to find which API endpoint or job feeds an empty username and fix the source of the bad data.
3. If calling from an internal loop, filter out null/blank usernames before processing the batch.

Example fix

// before
String roleName = VisibilityGrantRoleHelper.buildUserRoleName(username);

// after
if (StringUtils.isBlank(username)) {
    throw new IllegalArgumentException("username is blank");
}
String roleName = VisibilityGrantRoleHelper.buildUserRoleName(username);

if (StringUtils.isBlank(username)) {
    throw new IllegalArgumentException("username is blank");
}
// safe to call
String roleName = VisibilityGrantRoleHelper.buildUserRoleName(username);

static boolean isValidUsernameForRole(String username) {
    return username != null && !username.trim().isEmpty();
}

try {
    roleName = VisibilityGrantRoleHelper.buildUserRoleName(username);
} catch (IllegalArgumentException e) {
    // return 400 with validation message, do not retry
}

When it happens

Trigger: Calling buildUserRoleName(username) where username is null, an empty string "", or contains only whitespace. This happens when a visibility-grant granting API or persistence path receives a user identifier that was never validated upstream.

Common situations: A REST/controller layer passes a request DTO's username field straight into the visibility grant service without blank-checking it; or a background reconciliation/migration job iterates over a user list that contains null entries.

Related errors

• Plugin config value cannot be null: {key}
• Plugin config value must be positive: {key}
• Plugin config value is not a number: {key}
• Plugin config value is not a boolean: {key}
• PARAMETER_MISSING

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