RocketChat/Rocket.Chat · error · Error

error-contact-not-found

error-contact-not-found

Error message

error-contact-not-found

What it means

changeContactBlockStatus flips a contact's channel block flag via LivechatContacts.setChannelBlockStatus(visitor, block). When the update matches no document (modifiedCount === 0) it throws plain Error('error-contact-not-found'): no contact record carries the given visitor association (visitorId + channel).

Solutions

  1. Look the contact up by the same visitor association first and register it if missing
  2. Pass the exact visitorId + channel values used when the contact was created
  3. Re-run contact registration, then retry the block/unblock

Example fix

// before
await changeContactBlockStatus({ visitor: { visitorId, channel }, block: true }); // → error-contact-not-found

// after
const contact = await LivechatContacts.findOneByVisitorAssociation({ visitorId, channel });
if (!contact) await registerContact({ visitorId, channel });
await changeContactBlockStatus({ visitor: { visitorId, channel }, block: true });
Defensive patterns

Strategy: validation

Validate before calling

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

const contact = await LivechatContacts.findOneByVisitorAssociation({ visitorId, channel });
if (!contact) {
  throw new Error('no contact for this visitor association - register the contact first');
}
await changeContactBlockStatus({ visitor: { visitorId, channel }, block: true });

Try / catch

try {
  await changeContactBlockStatus({ visitor: association, block });
} catch (error) {
  if (error instanceof Error && error.message === 'error-contact-not-found') {
    // contact deleted concurrently or never registered: re-register then retry once
    await registerContact(association);
    return changeContactBlockStatus({ visitor: association, block });
  }
  throw error;
}

Prevention

When it happens

Trigger: Omnichannel contact block/unblock flow called with a visitorId + channel pair that matches no registered contact; or the contact was deleted between listing and blocking.

Common situations: Visitor exists but the contact-identification flow never created a contact record; passing a visitorId where the contact's stored association differs (wrong channel key); concurrent contact deletion.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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

Appendix: source

Thrown at apps/meteor/ee/server/api/v1/omnichannel/lib/contacts.ts:12

import type { IUser, ILivechatContactVisitorAssociation } from '@rocket.chat/core-typings';
import { License } from '@rocket.chat/license';
import { LivechatContacts, LivechatRooms, LivechatVisitors } from '@rocket.chat/models';

import { i18n } from '../../../../../../server/lib/i18n';
import { closeRoom } from '../../../../../../server/lib/omnichannel/closeRoom';

export async function changeContactBlockStatus({ block, visitor }: { visitor: ILivechatContactVisitorAssociation; block: boolean }) {
	const result = await LivechatContacts.setChannelBlockStatus(visitor, block);

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

export function ensureSingleContactLicense() {
	if (!License.hasModule('contact-id-verification')) {
		throw new Error('error-action-not-allowed');
	}
}

export async function closeBlockedRoom(association: ILivechatContactVisitorAssociation, user: IUser) {
	const visitor = await LivechatVisitors.findOneById(association.visitorId);

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

	const room = await LivechatRooms.findOneOpenByContactChannelVisitor(association);

View on GitHub (pinned to b2c16d5842)