RocketChat/Rocket.Chat · error · MeteorError

error-adding-monitor-role

error-adding-monitor-role

Error message

Error adding monitor role

What it means

Thrown by LivechatEnterprise.addMonitor when the user exists but addUserRolesAsync(user._id, ['livechat-monitor']) returns false — the roles subsystem refused to add the monitor role. MeteorError code 'error-adding-monitor-role', method 'livechat:addMonitor'. This is an infrastructure-level failure, not an input error.

Source

Thrown at apps/meteor/ee/server/lib/omnichannel/LivechatEnterprise.ts:27

import { removeSLAFromRooms } from './SlaHelper';
import { callbacks } from '../../../../server/lib/callbacks';
import { addUserRolesAsync } from '../../../../server/lib/roles/addUserRoles';
import { removeUserFromRolesAsync } from '../../../../server/lib/roles/removeUserFromRoles';

export const LivechatEnterprise = {
	async addMonitor(username: string) {
		const user = await Users.findOneByUsername<Pick<IUser, '_id' | 'username' | 'roles'>>(username, {
			projection: { _id: 1, username: 1, roles: 1 },
		});

		if (!user) {
			throw new MeteorError('error-invalid-user', 'Invalid user', {
				method: 'livechat:addMonitor',
			});
		}

		if (!(await addUserRolesAsync(user._id, ['livechat-monitor']))) {
			throw new MeteorError('error-adding-monitor-role', 'Error adding monitor role', {
				method: 'livechat:addMonitor',
			});
		}

		return user;
	},

	async removeMonitor(username: string) {
		const user = await Users.findOneByUsername<Pick<IUser, '_id'>>(username, {
			projection: { _id: 1 },
		});

		if (!user) {
			throw new Meteor.Error('error-invalid-user', 'Invalid user', {
				method: 'livechat:removeMonitor',
			});
		}

View on GitHub (pinned to f9d3ec372b)

Solutions

  1. Verify the 'livechat-monitor' role still exists in the roles collection.
  2. Check DB health and retry the addMonitor call once write connectivity is confirmed.
  3. Inspect addUserRolesAsync return path for the specific refusal reason and surface it.

Example fix

// before
if (!(await addUserRolesAsync(user._id, ['livechat-monitor']))) {
  throw new MeteorError('error-adding-monitor-role', 'Error adding monitor role');
}

// after: capture the reason
const ok = await addUserRolesAsync(user._id, ['livechat-monitor']);
if (!ok) throw new MeteorError('error-adding-monitor-role', `Role write failed for ${user._id}`);
Defensive patterns

Strategy: retry

Validate before calling

async function ensureMonitorRoleExists(): Promise<void> {
  const role = await Roles.findOneById('livechat-monitor');
  if (!role) throw new Error('livechat-monitor role missing');
}

Type guard

null

Try / catch

try { await LivechatEnterprise.addMonitor(username); } catch (e) {
  if (e?.error === 'error-adding-monitor-role') { /* verify role + DB health, retry once */ } else throw e;
}

Prevention

When it happens

Trigger: addUserRolesAsync returns false due to a roles-collection write failure, an invalid role definition for 'livechat-monitor', or a DB error during the role assignment; concurrent modification of the user's roles.

Common situations: Roles collection inconsistency; DB connectivity blip during the write; 'livechat-monitor' role was deleted from the system; permission/role helper changed signature.

Related errors

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