What causes "Error adding monitor role" in RocketChat/Rocket.Chat?

Ensure default roles are seeded: run pending migrations or restart so 'livechat-monitor' is created

RocketChat/Rocket.Chat · error · MeteorError

error-adding-monitor-role

error-adding-monitor-role

Error message

Error adding monitor role

What it means

The username lookup succeeded, but addUserRolesAsync(user._id, ['livechat-monitor']) returned false: the roles write did not acknowledge adding the livechat-monitor role to the user.

Solutions

Ensure default roles are seeded: run pending migrations or restart so 'livechat-monitor' is created
Inspect the Roles collection for 'livechat-monitor' and re-create it if absent
Check MongoDB logs/health for the failing role update

Defensive patterns

Strategy: try-catch

Validate before calling

const roleExists = await Roles.findOneById('livechat-monitor');
if (!roleExists) {
	// seed roles / run migrations before adding monitors
}

Try / catch

try {
	await LivechatEnterprise.addMonitor(username);
} catch (err) {
	if ((err as Meteor.Error)?.error === 'error-adding-monitor-role') {
		// the user existed but the role write failed: check Roles collection and Mongo health
	} else {
		throw err;
	}
}

Prevention

Run pending migrations on upgraded instances so default roles exist
Never delete built-in roles manually
Include a roles-seeded assertion in deployment health checks

When it happens

Trigger: The 'livechat-monitor' role is missing from the Roles collection (fresh or partially migrated instance), or the roles update failed at the database level.

Common situations: Database restored without seed roles; migrations skipped on an old instance; role removed manually; replica set write failures.

Related errors

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

Appendix: 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 b2c16d5842)