{"record":{"id":"ea55c82a7683db2e","repo":"RocketChat/Rocket.Chat","slug":"error-contact-manager-not-found","errorCode":"error-contact-manager-not-found","errorMessage":"No user found with username ${contactManager.username}","messagePattern":"No user found with username (.+?)","errorType":"error_code","errorClass":"MeteorError","httpStatus":null,"severity":"error","filePath":"apps/meteor/server/lib/omnichannel/contacts/registerContact.ts","lineNumber":38,"sourceCode":"\t\tusername: string;\n\t};\n};\n\nexport async function registerContact(\n\t{ token, name, email = '', phone, username, customFields = {}, contactManager }: RegisterContactProps,\n\tuserId: string,\n): Promise<string> {\n\tif (!token || typeof token !== 'string') {\n\t\tthrow new MeteorError('error-invalid-contact-data', 'Invalid visitor token');\n\t}\n\n\tconst visitorEmail = email.trim().toLowerCase();\n\n\tif (contactManager?.username) {\n\t\t// verify if the user exists with this username and has a livechat-agent role\n\t\tconst manager = await Users.findOneByUsername(contactManager.username, { projection: { roles: 1 } });\n\t\tif (!manager) {\n\t\t\tthrow new MeteorError('error-contact-manager-not-found', `No user found with username ${contactManager.username}`);\n\t\t}\n\t\tif (!manager.roles || !Array.isArray(manager.roles) || !manager.roles.includes('livechat-agent')) {\n\t\t\tthrow new MeteorError('error-invalid-contact-manager', 'The contact manager must have the role \"livechat-agent\"');\n\t\t}\n\t}\n\n\tconst existingUserByToken = await LivechatVisitors.getVisitorByToken(token, { projection: { _id: 1 } });\n\tlet visitorId = existingUserByToken?._id;\n\n\tif (!existingUserByToken) {\n\t\tif (!username) {\n\t\t\tusername = await LivechatVisitors.getNextVisitorUsername();\n\t\t}\n\n\t\tconst existingUserByEmail = await LivechatVisitors.findOneGuestByEmailAddress(visitorEmail);\n\t\tvisitorId = existingUserByEmail?._id;\n\n\t\tif (!existingUserByEmail) {","sourceCodeStart":20,"sourceCodeEnd":56,"githubUrl":"https://github.com/RocketChat/Rocket.Chat/blob/b2c16d5842cbe6b69b59bdf6fc5e5f1afcd1f0b0/apps/meteor/server/lib/omnichannel/contacts/registerContact.ts#L20-L56","documentation":"Thrown by registerContact (reached via POST /api/v1/omnichannel/contact) when the request body includes a contactManager.username but no Users document matches that username. The registration validates the manager up-front, before creating or linking the visitor/contact, because a contact manager must reference a real user. The interpolated message echoes the exact username that failed the lookup.","triggerScenarios":"Calling the omnichannel contact register endpoint (or registerContact directly) with contactManager.username set to a value that has no matching Users record: typo, wrong case, deleted/merged user, or a username sourced from LDAP/SCIM sync that diverges from Rocket.Chat's username.","commonSituations":"Client stores email or display name where the API expects the Rocket.Chat username; the agent account was renamed or deactivated after the client cached it; external sync provisioned users under different usernames than expected.","solutions":["Verify the exact username with GET /api/v1/users.info?username=... (usernames are case-sensitive) and correct the payload","Confirm the user still exists and is not deleted or merged into another account","If no manager is intended, omit the contactManager object entirely from the request instead of sending an empty/placeholder username","If syncing from an external directory, re-sync so the username mapping matches Rocket.Chat"],"exampleFix":"// before\nawait registerContact({ token, email, contactManager: { username: 'john.doe' } }, userId); // 'john.doe' does not exist\n\n// after\nconst manager = await Users.findOneByUsername('johndoe', { projection: { _id: 1 } });\nif (!manager) throw new MeteorError('error-contact-manager-not-found', 'Unknown manager');\nawait registerContact({ token, email, contactManager: { username: 'johndoe' } }, userId);","handlingStrategy":"validation","validationCode":"const manager = await Users.findOneByUsername(contactManager.username, { projection: { _id: 1, username: 1 } });\nif (!manager) {\n  throw new Error(`Unknown contact manager username: ${contactManager.username}`);\n}\nawait registerContact({ ...params, contactManager: { username: manager.username } }, userId);","typeGuard":"const isContactManagerRef = (v: unknown): v is { username: string } =>\n  typeof v === 'object' && v !== null && typeof (v as { username?: unknown }).username === 'string' && (v as { username: string }).username.length > 0;","tryCatchPattern":"try {\n  await registerContact(params, userId);\n} catch (err) {\n  if (err instanceof MeteorError && err.code === 'error-contact-manager-not-found') {\n    // surface 'manager username does not exist' to the caller; do not retry with same payload\n  }\n  throw err;\n}","preventionTips":["Resolve manager usernames through users.info right before the call instead of caching them","Never substitute email or display name for the username field","Keep contactManager omitted when no manager is intended"],"tags":["omnichannel","livechat","contacts","contact-manager","user-lookup","validation"],"backgroundTag":"user-not-found","analyzedSha":"b2c16d5842cbe6b69b59bdf6fc5e5f1afcd1f0b0","analyzedAt":"2026-08-18T15:26:39.429Z","schemaVersion":2},"datasetVersion":"2026-08-21T13:17:26.733Z"}