{"record":{"id":"f096e46617509a49","repo":"RocketChat/Rocket.Chat","slug":"error-adding-monitor-role","errorCode":"error-adding-monitor-role","errorMessage":"Error adding monitor role","messagePattern":"Error adding monitor role","errorType":"exception","errorClass":"MeteorError","httpStatus":null,"severity":"error","filePath":"apps/meteor/ee/server/lib/omnichannel/LivechatEnterprise.ts","lineNumber":27,"sourceCode":"import { removeSLAFromRooms } from './SlaHelper';\nimport { callbacks } from '../../../../server/lib/callbacks';\nimport { addUserRolesAsync } from '../../../../server/lib/roles/addUserRoles';\nimport { removeUserFromRolesAsync } from '../../../../server/lib/roles/removeUserFromRoles';\n\nexport const LivechatEnterprise = {\n\tasync addMonitor(username: string) {\n\t\tconst user = await Users.findOneByUsername<Pick<IUser, '_id' | 'username' | 'roles'>>(username, {\n\t\t\tprojection: { _id: 1, username: 1, roles: 1 },\n\t\t});\n\n\t\tif (!user) {\n\t\t\tthrow new MeteorError('error-invalid-user', 'Invalid user', {\n\t\t\t\tmethod: 'livechat:addMonitor',\n\t\t\t});\n\t\t}\n\n\t\tif (!(await addUserRolesAsync(user._id, ['livechat-monitor']))) {\n\t\t\tthrow new MeteorError('error-adding-monitor-role', 'Error adding monitor role', {\n\t\t\t\tmethod: 'livechat:addMonitor',\n\t\t\t});\n\t\t}\n\n\t\treturn user;\n\t},\n\n\tasync removeMonitor(username: string) {\n\t\tconst user = await Users.findOneByUsername<Pick<IUser, '_id'>>(username, {\n\t\t\tprojection: { _id: 1 },\n\t\t});\n\n\t\tif (!user) {\n\t\t\tthrow new Meteor.Error('error-invalid-user', 'Invalid user', {\n\t\t\t\tmethod: 'livechat:removeMonitor',\n\t\t\t});\n\t\t}\n","sourceCodeStart":9,"sourceCodeEnd":45,"githubUrl":"https://github.com/RocketChat/Rocket.Chat/blob/f9d3ec372bb580fa8d036f94cf03925a478ef768/apps/meteor/ee/server/lib/omnichannel/LivechatEnterprise.ts#L9-L45","documentation":"Thrown by LivechatEnterprise.addMonitor when the user exists but addUserRolesAsync(user._id, ['livechat-monitor']) returns false — the roles subsystem refused to add the monitor role. MeteorError code 'error-adding-monitor-role', method 'livechat:addMonitor'. This is an infrastructure-level failure, not an input error.","triggerScenarios":"addUserRolesAsync returns false due to a roles-collection write failure, an invalid role definition for 'livechat-monitor', or a DB error during the role assignment; concurrent modification of the user's roles.","commonSituations":"Roles collection inconsistency; DB connectivity blip during the write; 'livechat-monitor' role was deleted from the system; permission/role helper changed signature.","solutions":["Verify the 'livechat-monitor' role still exists in the roles collection.","Check DB health and retry the addMonitor call once write connectivity is confirmed.","Inspect addUserRolesAsync return path for the specific refusal reason and surface it."],"exampleFix":"// before\nif (!(await addUserRolesAsync(user._id, ['livechat-monitor']))) {\n  throw new MeteorError('error-adding-monitor-role', 'Error adding monitor role');\n}\n\n// after: capture the reason\nconst ok = await addUserRolesAsync(user._id, ['livechat-monitor']);\nif (!ok) throw new MeteorError('error-adding-monitor-role', `Role write failed for ${user._id}`);","handlingStrategy":"retry","validationCode":"async function ensureMonitorRoleExists(): Promise<void> {\n  const role = await Roles.findOneById('livechat-monitor');\n  if (!role) throw new Error('livechat-monitor role missing');\n}","typeGuard":"null","tryCatchPattern":"try { await LivechatEnterprise.addMonitor(username); } catch (e) {\n  if (e?.error === 'error-adding-monitor-role') { /* verify role + DB health, retry once */ } else throw e;\n}","preventionTips":["Ensure the 'livechat-monitor' role is seeded in the roles collection.","Treat addMonitor failures as transient; surface DB/role health to admins."],"tags":["omnichannel","monitor","roles","enterprise"],"backgroundTag":null,"analyzedSha":"f9d3ec372bb580fa8d036f94cf03925a478ef768","analyzedAt":"2026-08-12T19:07:17.372Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}