RocketChat/Rocket.Chat · error · Error

invalid-user

invalid-user

Error message

invalid-user

What it means

findMonitorByUsername queries Users.findOne({ username, roles: 'livechat-monitor' }). It throws 'invalid-user' when no user with that exact username holds the livechat-monitor role — so both an unknown username and a valid username without the monitor role produce the same error.

Solutions

  1. Add the livechat-monitor role to the user (Administration → Omnichannel → Monitors)
  2. List valid monitors via the monitors list endpoint and use an existing monitor's username
  3. Double-check the username spelling — matching is exact, not case-insensitive

Example fix

// before
await findMonitorByUsername({ username: 'sam.agent' }); // agent without livechat-monitor role → invalid-user

// after
await Roles.addUserRoles('sam.agent', ['livechat-monitor']);
await findMonitorByUsername({ username: 'sam.agent' });
Defensive patterns

Strategy: validation

Validate before calling

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

const isMonitor = await Users.findOne({ username, roles: 'livechat-monitor' }, { projection: { _id: 1 } });
if (!isMonitor) {
  throw new Error(`'${username}' is not a livechat monitor (role missing or wrong username)`);
}
await findMonitorByUsername({ username });

Try / catch

try {
  await findMonitorByUsername({ username });
} catch (error) {
  if (error instanceof Error && error.message === 'invalid-user') {
    throw new NotFoundError(`no livechat-monitor with username '${username}' - add the role first`);
  }
  throw error;
}

Prevention

When it happens

Trigger: Omnichannel monitor endpoints that resolve a monitor by username, called with an agent/admin username that lacks the livechat-monitor role, or with a typo'd username.

Common situations: Forgetting to promote a user to monitor in Omnichannel settings; username vs user-id mix-ups (this lookup wants the username); case mismatches — the query is exact.

Understand the failure class

Background: "User not found", "Invalid user", and "does not exist": what missing-user lookup errors mean across Rocket.Chat, LiteLLM, Phabricator, rustfs, and pnpm — this error's family across 10 libraries.

Related errors

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

Appendix: source

Thrown at apps/meteor/ee/server/api/v1/omnichannel/lib/monitors.ts:67

}

export async function findMonitorByUsername({ username }: { username: string }): Promise<IUser> {
	const user = await Users.findOne(
		{ username, roles: 'livechat-monitor' },
		{
			projection: {
				username: 1,
				name: 1,
				status: 1,
				statusLivechat: 1,
				emails: 1,
				livechat: 1,
			},
		},
	);

	if (!user) {
		throw new Error('invalid-user');
	}

	return user;
}

View on GitHub (pinned to b2c16d5842)