{"record":{"id":"85fa242e0b60b17d","repo":"RocketChat/Rocket.Chat","slug":"invalid-user-85fa24","errorCode":"invalid-user","errorMessage":"invalid-user","messagePattern":"invalid-user","errorType":"exception","errorClass":"Error","httpStatus":400,"severity":"error","filePath":"apps/meteor/ee/server/api/v1/omnichannel/lib/monitors.ts","lineNumber":67,"sourceCode":"}\n\nexport async function findMonitorByUsername({ username }: { username: string }): Promise<IUser> {\n\tconst user = await Users.findOne(\n\t\t{ username, roles: 'livechat-monitor' },\n\t\t{\n\t\t\tprojection: {\n\t\t\t\tusername: 1,\n\t\t\t\tname: 1,\n\t\t\t\tstatus: 1,\n\t\t\t\tstatusLivechat: 1,\n\t\t\t\temails: 1,\n\t\t\t\tlivechat: 1,\n\t\t\t},\n\t\t},\n\t);\n\n\tif (!user) {\n\t\tthrow new Error('invalid-user');\n\t}\n\n\treturn user;\n}\n","sourceCodeStart":49,"sourceCodeEnd":72,"githubUrl":"https://github.com/RocketChat/Rocket.Chat/blob/b2c16d5842cbe6b69b59bdf6fc5e5f1afcd1f0b0/apps/meteor/ee/server/api/v1/omnichannel/lib/monitors.ts#L49-L72","documentation":"findMonitorByUsername queries Users.findOne({ username, roles: 'livechat-monitor' }). It throws 'invalid-user' when no user with that exact username holds the livechat-monitor role — so both an unknown username and a valid username without the monitor role produce the same error.","triggerScenarios":"Omnichannel monitor endpoints that resolve a monitor by username, called with an agent/admin username that lacks the livechat-monitor role, or with a typo'd username.","commonSituations":"Forgetting to promote a user to monitor in Omnichannel settings; username vs user-id mix-ups (this lookup wants the username); case mismatches — the query is exact.","solutions":["Add the livechat-monitor role to the user (Administration → Omnichannel → Monitors)","List valid monitors via the monitors list endpoint and use an existing monitor's username","Double-check the username spelling — matching is exact, not case-insensitive"],"exampleFix":"// before\nawait findMonitorByUsername({ username: 'sam.agent' }); // agent without livechat-monitor role → invalid-user\n\n// after\nawait Roles.addUserRoles('sam.agent', ['livechat-monitor']);\nawait findMonitorByUsername({ username: 'sam.agent' });","handlingStrategy":"validation","validationCode":"import { Users } from '@rocket.chat/models';\n\nconst isMonitor = await Users.findOne({ username, roles: 'livechat-monitor' }, { projection: { _id: 1 } });\nif (!isMonitor) {\n  throw new Error(`'${username}' is not a livechat monitor (role missing or wrong username)`);\n}\nawait findMonitorByUsername({ username });","typeGuard":null,"tryCatchPattern":"try {\n  await findMonitorByUsername({ username });\n} catch (error) {\n  if (error instanceof Error && error.message === 'invalid-user') {\n    throw new NotFoundError(`no livechat-monitor with username '${username}' - add the role first`);\n  }\n  throw error;\n}","preventionTips":["Promote users to livechat-monitor before referencing them as monitors","This API keys on username, not user id — do not mix them","Offer monitor selection from the monitors list endpoint, not free-text input"],"tags":["omnichannel","livechat","monitors","user-lookup"],"backgroundTag":"user-not-found","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"}