alibaba/nacos · warning · IllegalArgumentException

role {role} not found!

Error message

role {role} not found!

What it means

Thrown by addPermission(role, resource, action) when the role is not present in the in-memory cachedRoleSet. Permissions can only be attached to roles that already exist, so the service validates role existence against the cache before persisting the permission. If the cache was not warmed, or the role was never created, the permission is rejected with IllegalArgumentException.

Source

Thrown at plugin-default-impl/nacos-default-auth-plugin/src/main/java/com/alibaba/nacos/plugin/auth/impl/roles/NacosRoleServiceDirectImpl.java:181

    
    @Override
    public void deleteRole(String role, String userName) {
        rejectReservedRole(role);
        rolePersistService.deleteRole(role, userName);
        invalidateUserRoles(userName);
    }
    
    @Override
    public void deleteRole(String role) {
        rejectReservedRole(role);
        rolePersistService.deleteRole(role);
        getCachedRoleInfoMap().remove(role);
    }
    
    @Override
    public void addPermission(String role, String resource, String action) {
        if (!getCachedRoleSet().contains(role)) {
            throw new IllegalArgumentException("role " + role + " not found!");
        }
        permissionPersistService.addPermission(role, resource, action);
        invalidateRolePermissions(role);
    }
    
    @Override
    public void deletePermission(String role, String resource, String action) {
        permissionPersistService.deletePermission(role, resource, action);
        invalidateRolePermissions(role);
    }
    
    @Override
    public Page<RoleInfo> findRoles(String username, String role, int pageNo, int pageSize) {
        return rolePersistService.findRolesLike4Page(username, role, pageNo, pageSize);
    }
    
    @Override
    public List<String> findRoleNames(String role) {

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Create the role first via roleService.addRole(role, username), then add permissions.
2. If the role should already exist, trigger a role-cache reload (or wait for sync) before retrying.
3. Verify the exact role name against getRoles before adding permissions.

Example fix

// before
permissionService.addPermission("ROLE_DEV", "/ns/**", "r"); // role not in cache

// after
if (!roleService.getCachedRoleSet().contains("ROLE_DEV")) {
    roleService.addRole("ROLE_DEV", ownerUsername);
}
permissionService.addPermission("ROLE_DEV", "/ns/**", "r");

if (!roleService.getCachedRoleSet().contains(role)) {
    throw new IllegalStateException("Cannot add permission: role '" + role + "' does not exist");
}
roleService.addPermission(role, resource, action);

When it happens

Trigger: POST /v3/admin/auth/permission for a role name that was never created; calling addPermission immediately after server start before the role cache is loaded; referencing a deleted role.

Common situations: Creating permissions before the role exists; cache not yet warmed on a freshly started node; role was created on another node and replication/cache-sync has not completed; typo in role name.

Related errors

• user '{username}' not found!
• role 'ROLE_ADMIN' is not permitted to create!
• role '__nacos_anonymous_role__' 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/b83b5383b41133c8. Report an issue: GitHub.