{"record":{"id":"182de20cf8fe509f","repo":"RocketChat/Rocket.Chat","slug":"error-contact-not-found-182de2","errorCode":"error-contact-not-found","errorMessage":"error-contact-not-found","messagePattern":"error-contact-not-found","errorType":"error_code","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"apps/meteor/server/lib/omnichannel/contacts/addContactEmail.ts","lineNumber":16,"sourceCode":"import type { ILivechatContact } from '@rocket.chat/core-typings';\nimport { LivechatContacts } from '@rocket.chat/models';\n\n/**\n * Adds a new email into the contact's email list, if the email is already in the list it does not add anything\n * and simply return the data, since the email was aready registered :P\n *\n * @param contactId the id of the contact that will be updated\n * @param email the email that will be added to the contact\n * @returns the updated contact\n */\nexport async function addContactEmail(contactId: ILivechatContact['_id'], email: string): Promise<ILivechatContact> {\n\tconst contact = await LivechatContacts.addEmail(contactId, email);\n\n\tif (!contact) {\n\t\tthrow new Error('error-contact-not-found');\n\t}\n\n\treturn contact;\n}\n","sourceCodeStart":1,"sourceCodeEnd":21,"githubUrl":"https://github.com/RocketChat/Rocket.Chat/blob/b2c16d5842cbe6b69b59bdf6fc5e5f1afcd1f0b0/apps/meteor/server/lib/omnichannel/contacts/addContactEmail.ts#L1-L21","documentation":"addContactEmail delegates to LivechatContacts.addEmail(contactId, email), which returns the updated contact or null when no document matched the id; the wrapper throws Error('error-contact-not-found') on null. The supplied contactId simply does not exist in the LivechatContacts collection.","triggerScenarios":"Calling the contact-email flow with a contactId that was deleted, belongs to another workspace, or is actually a visitor token or user id mistaken for a contact _id.","commonSituations":"Integrations caching contact ids beyond their lifetime; id-space confusion between visitor tokens, user ids, and contact ids; contacts removed by GDPR/privacy cleanup jobs.","solutions":["Verify the contact exists and is enabled (LivechatContacts.findOneEnabledById) before adding the email","Re-resolve the contact from a stable key (e.g. a channel's visitor token) instead of trusting a cached id","Respond with a not-found outcome - this error is not transient, retrying cannot succeed"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"import { LivechatContacts } from '@rocket.chat/models';\n\nconst contact = await LivechatContacts.findOneEnabledById(contactId, { projection: { _id: 1 } });\nif (!contact) {\n  // don't call addContactEmail: re-resolve the contact or return not-found\n}","typeGuard":null,"tryCatchPattern":"try {\n  const updated = await addContactEmail(contactId, email);\n} catch (err: any) {\n  if (err?.message === 'error-contact-not-found') return respondNotFound(contactId);\n  throw err;\n}","preventionTips":["Treat contact ids as ephemeral: re-resolve them from stable channel keys (visitor token, email)","Respond 404 immediately on this error - retries cannot succeed","Never copy contact ids between workspaces or environments"],"tags":["omnichannel","contacts","not-found","livechat"],"backgroundTag":"contact-not-found","analyzedSha":"b2c16d5842cbe6b69b59bdf6fc5e5f1afcd1f0b0","analyzedAt":"2026-08-18T15:26:39.429Z","schemaVersion":2},"datasetVersion":"2026-08-21T18:17:14.833Z"}