{"record":{"id":"a1f595c2d721fa92","repo":"alibaba/nacos","slug":"user-username-not-found","errorCode":null,"errorMessage":"user '{username}' not found!","messagePattern":"user '(.+?)' not found!","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"warning","filePath":"plugin-default-impl/nacos-default-auth-plugin/src/main/java/com/alibaba/nacos/plugin/auth/impl/roles/NacosRoleServiceDirectImpl.java","lineNumber":126,"sourceCode":"            }\n        }\n        return permissionInfoList;\n    }\n    \n    @Override\n    public Page<PermissionInfo> getPermissions(String role, int pageNo, int pageSize) {\n        Page<PermissionInfo> pageInfo =\n            permissionPersistService.getPermissions(role, pageNo, pageSize);\n        if (pageInfo == null) {\n            return new Page<>();\n        }\n        return pageInfo;\n    }\n    \n    @Override\n    public void addRole(String role, String username) {\n        if (userDetailsService.getUser(username) == null) {\n            throw new IllegalArgumentException(\"user '\" + username + \"' not found!\");\n        }\n        \n        if (AuthConstants.GLOBAL_ADMIN_ROLE.equals(role)) {\n            throw new IllegalArgumentException(\n                \"role '\" + AuthConstants.GLOBAL_ADMIN_ROLE + \"' is not permitted to create!\");\n        }\n        \n        if (AuthConstants.ANONYMOUS_ROLE.equals(role)) {\n            throw new IllegalArgumentException(\n                \"role '\" + AuthConstants.ANONYMOUS_ROLE + \"' is reserved by the system\");\n        }\n        \n        if (isUserBoundToRole(role, username)) {\n            throw new IllegalArgumentException(\n                \"user '\" + username + \"' already bound to the role '\" + role + \"'!\");\n        }\n        \n        rolePersistService.addRole(role, username);","sourceCodeStart":108,"sourceCodeEnd":144,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/plugin-default-impl/nacos-default-auth-plugin/src/main/java/com/alibaba/nacos/plugin/auth/impl/roles/NacosRoleServiceDirectImpl.java#L108-L144","documentation":"Thrown by NacosRoleServiceDirectImpl.addRole(role, username) when binding a role to a user that does not exist in the user store. The service calls userDetailsService.getUser(username); a null return means no such user is persisted, so the role binding is rejected before touching the database. It is an IllegalArgumentException, so it surfaces to the caller as a 400-style validation failure, not a server error.","triggerScenarios":"POST /v3/admin/auth/role (or console equivalent) with a 'username' parameter for a user that was never created, was deleted, or is misspelled. Also triggered programmatically via NacosRoleService.addRole after a user was removed in another node and the local cache is stale.","commonSituations":"Creating a role assignment before creating the user; case-sensitivity mismatch on the username; referencing a user that was just deleted by another admin; scripts that provision roles and users out of order.","solutions":["Create the user first (POST /v3/admin/auth/user or userService.createUser) before assigning the role.","Verify the exact username with GET /v3/admin/auth/user?username=<value>, matching case.","If the user was recently deleted, re-create it, then retry the role binding.","In clustered setups, ensure user creation has replicated to the node handling the addRole call."],"exampleFix":"// before\nroleService.addRole(\"ROLE_DEV\", \"alice\"); // throws if alice missing\n\n// after\nif (userService.getUser(\"alice\") == null) {\n    userService.createUser(\"alice\", password);\n}\nroleService.addRole(\"ROLE_DEV\", \"alice\");","handlingStrategy":"validation","validationCode":"// Verify the user exists before binding a role.\nif (userDetailsService.getUser(username) == null) {\n    throw new IllegalStateException(\"Cannot bind role: user '\" + username + \"' does not exist\");\n}\nroleService.addRole(role, username);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always create the user before assigning roles to it.","Wrap provisioning in a single transaction/sequence: user -> role -> permission.","Validate usernames against the user store before any role operation."],"tags":["auth","role","validation","user-management"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}