{"record":{"id":"c4898f7d362d5c96","repo":"RocketChat/Rocket.Chat","slug":"error-role-in-use","errorCode":"error-role-in-use","errorMessage":"Cannot delete role because it's in use","messagePattern":"Cannot delete role because it's in use","errorType":"exception","errorClass":"Meteor.Error","httpStatus":400,"severity":"error","filePath":"apps/meteor/server/api/v1/roles.ts","lineNumber":247,"sourceCode":"\t\t\t\t401: validateUnauthorizedErrorResponse,\n\t\t\t\t403: validateForbiddenErrorResponse,\n\t\t\t},\n\t\t},\n\t\tasync function action() {\n\t\t\tconst { bodyParams } = this;\n\n\t\t\tconst role = await Roles.findOneByIdOrName(bodyParams.roleId);\n\n\t\t\tif (!role) {\n\t\t\t\tthrow new Meteor.Error('error-invalid-roleId', 'This role does not exist');\n\t\t\t}\n\n\t\t\tif (role.protected) {\n\t\t\t\tthrow new Meteor.Error('error-role-protected', 'Cannot delete a protected role');\n\t\t\t}\n\n\t\t\tif ((await Roles.countUsersInRole(role._id)) > 0) {\n\t\t\t\tthrow new Meteor.Error('error-role-in-use', \"Cannot delete role because it's in use\");\n\t\t\t}\n\n\t\t\tawait Roles.removeById(role._id);\n\n\t\t\tvoid notifyOnRoleChanged(role, 'removed');\n\n\t\t\treturn API.v1.success();\n\t\t},\n\t)\n\t.post(\n\t\t'roles.removeUserFromRole',\n\t\t{\n\t\t\tauthRequired: true,\n\t\t\tpermissionsRequired: ['access-permissions'],\n\t\t\tbody: isRoleRemoveUserFromRoleProps,\n\t\t\tresponse: {\n\t\t\t\t200: ajv.compile<{ role: IRole }>({\n\t\t\t\t\ttype: 'object',","sourceCodeStart":229,"sourceCodeEnd":265,"githubUrl":"https://github.com/RocketChat/Rocket.Chat/blob/b2c16d5842cbe6b69b59bdf6fc5e5f1afcd1f0b0/apps/meteor/server/api/v1/roles.ts#L229-L265","documentation":"Thrown by POST /api/v1/roles.delete when Roles.countUsersInRole(role._id) is greater than zero — users (or room-scoped assignments) still reference the role. Referential integrity requires the role to be empty before removal; this is the last guard, after existence and protected checks pass.","triggerScenarios":"POST /api/v1/roles.delete on a custom role that still has members — e.g. an onboarding role granted to every new user, or a room-scoped role still assigned inside channels. The role exists, is not protected, but countUsersInRole returns > 0.","commonSituations":"Decommissioning a department role while staff still hold it; forgetting room-scoped assignments (moderator in a channel counts); bulk scripts deleting roles before unassigning them.","solutions":["List members first: GET /api/v1/roles.getUsersInRole?role=<id> to see who holds it","Remove them: POST /api/v1/roles.removeUserFromRole { roleId, username, roomId? } for each (remember room-scoped grants need the roomId)","Retry roles.delete only after the users list comes back empty"],"exampleFix":"// before\nawait sdk.post('roles.delete', { roleId });\n\n// after (drain members, then delete)\nconst { users } = await sdk.get('roles.getUsersInRole', { role: roleId, count: 0 });\nfor (const u of users) await sdk.post('roles.removeUserFromRole', { roleId, username: u.username });\nawait sdk.post('roles.delete', { roleId });","handlingStrategy":"validation","validationCode":"// confirm the role is empty before attempting deletion\nconst { total } = await sdk.get('roles.getUsersInRole', { role: role._id, count: 1 });\nif (total > 0) throw new Error(`role still has ${total} assignee(s) — remove them first`);\nawait sdk.post('roles.delete', { roleId: role._id });","typeGuard":null,"tryCatchPattern":"catch 'error-role-in-use', fetch members via roles.getUsersInRole, remove each with roles.removeUserFromRole (passing roomId for room-scoped grants), then retry the delete; treat repeated failure as leftover room-scoped assignments.","preventionTips":["Always drain members before deleting a role (script: list → unassign → delete)","Remember room-scoped grants count as in-use even if no user lists the role globally","Pair role decommissioning with the LDAP/SCIM sync that may re-add members"],"tags":["roles","users","referential-integrity","rest-api","lifecycle"],"backgroundTag":"resource-in-use","analyzedSha":"b2c16d5842cbe6b69b59bdf6fc5e5f1afcd1f0b0","analyzedAt":"2026-08-18T15:26:39.429Z","contentChangedAt":"2026-08-18T15:26:39.429Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}