RocketChat/Rocket.Chat · error · Error

error-contact-not-found

error-contact-not-found

Error message

error-contact-not-found

What it means

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.

Source

Thrown at apps/meteor/server/lib/omnichannel/contacts/addContactEmail.ts:16

import type { ILivechatContact } from '@rocket.chat/core-typings';
import { LivechatContacts } from '@rocket.chat/models';

/**
 * Adds a new email into the contact's email list, if the email is already in the list it does not add anything
 * and simply return the data, since the email was aready registered :P
 *
 * @param contactId the id of the contact that will be updated
 * @param email the email that will be added to the contact
 * @returns the updated contact
 */
export async function addContactEmail(contactId: ILivechatContact['_id'], email: string): Promise<ILivechatContact> {
	const contact = await LivechatContacts.addEmail(contactId, email);

	if (!contact) {
		throw new Error('error-contact-not-found');
	}

	return contact;
}

View on GitHub (pinned to b2c16d5842)

Solutions

  1. Verify the contact exists and is enabled (LivechatContacts.findOneEnabledById) before adding the email
  2. Re-resolve the contact from a stable key (e.g. a channel's visitor token) instead of trusting a cached id
  3. Respond with a not-found outcome - this error is not transient, retrying cannot succeed
Defensive patterns

Strategy: validation

Validate before calling

import { LivechatContacts } from '@rocket.chat/models';

const contact = await LivechatContacts.findOneEnabledById(contactId, { projection: { _id: 1 } });
if (!contact) {
  // don't call addContactEmail: re-resolve the contact or return not-found
}

Try / catch

try {
  const updated = await addContactEmail(contactId, email);
} catch (err: any) {
  if (err?.message === 'error-contact-not-found') return respondNotFound(contactId);
  throw err;
}

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of RocketChat/Rocket.Chat@b2c16d5842 (2026-08-18). Data as JSON: /api/errors/182de20cf8fe509f. Report an issue: GitHub.