RocketChat/Rocket.Chat · error · Error

error-contact-manager-not-found

error-contact-manager-not-found

Error message

error-contact-manager-not-found

What it means

validateContactManager is the id-based manager check used by updateContact and resolveContactConflicts. Users.findOneAgentById looks a user up by _id AND requires them to be an agent; null means the passed contactManagerUserId either does not exist or lacks the livechat-agent role. Note the contrast with registerContact, which validates by username — here the caller must supply the manager's user _id.

Source

Thrown at apps/meteor/server/lib/omnichannel/contacts/validateContactManager.ts:7

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

export async function validateContactManager(contactManagerUserId: string) {
	const contactManagerUser = await Users.findOneAgentById<Pick<IUser, '_id'>>(contactManagerUserId, { projection: { _id: 1 } });
	if (!contactManagerUser) {
		throw new Error('error-contact-manager-not-found');
	}
}

View on GitHub (pinned to b2c16d5842)

Solutions

  1. Confirm you are sending the manager's user _id (not username/email) — resolve it first via users.info if needed
  2. Verify the id maps to an agent: GET /api/v1/livechat/agents or users.info showing the 'livechat-agent' role
  3. Add the livechat-agent role to the intended manager, or omit contactManager / send it empty to unset a manager

Example fix

// before
await updateContact({ contactId, contactManager: 'johndoe' }); // username, not _id

// after
const { user } = await GET('/api/v1/users.info?username=johndoe');
await updateContact({ contactId, contactManager: user._id });
Defensive patterns

Strategy: validation

Validate before calling

const agent = await Users.findOneAgentById(contactManagerUserId, { projection: { _id: 1 } });
if (!agent) throw new Error('contactManager must be an existing livechat agent user _id');
await updateContact({ ...params, contactManager: contactManagerUserId });

Type guard

const isAgentUserId = (v: unknown): v is string =>
  typeof v === 'string' && /^[0-9a-f]{17}$/i.test(v); // user _id shape, NOT a username

Try / catch

try {
  await updateContact(params);
} catch (err) {
  if (err instanceof Error && err.message === 'error-contact-manager-not-found') {
    // id unknown or user lacks livechat-agent role: resolve real agent _id via livechat/agents and retry
  }
  throw err;
}

Prevention

When it happens

Trigger: POST/PUT contact endpoints with contactManager set to a user id that is unknown, deleted, or not a livechat agent; very commonly, passing the manager's username or email where the _id is required.

Common situations: Client sends username instead of _id because the register endpoint uses username; agent removed from the agent list but still referenced by old records; user record purged by a retention job.

Related errors

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