What causes "invalid-agent" in RocketChat/Rocket.Chat?

Verify the agent user referenced in room.servedBy._id still exists in the Users collection.

RocketChat/Rocket.Chat · error · Error

invalid-agent

Error message

invalid-agent

What it means

Thrown by GET /api/v1/livechat/agent.info/:rid/:token when findAgent(room.servedBy._id) returns null. The room has a servedBy reference (indicating an agent was assigned) but the agent's user record cannot be found via normalizeAgent. This indicates a data integrity issue — the room references an agent who no longer exists.

Source

Thrown at apps/meteor/server/api/v1/omnichannel/agent.ts:38

import { saveAgentInfo } from '../../../lib/omnichannel/omni-users';
import { setUserStatusLivechat, allowAgentChangeServiceStatus } from '../../../lib/omnichannel/utils';
import type { ExtractRoutesFromAPI } from '../../ApiClass';

API.v1.addRoute('livechat/agent.info/:rid/:token', {
	async get() {
		const visitor = await findGuest(this.urlParams.token);
		if (!visitor) {
			throw new Error('invalid-token');
		}

		const room = await findRoom(this.urlParams.token, this.urlParams.rid);
		if (!room) {
			throw new Error('invalid-room');
		}

		const agent = room?.servedBy && (await findAgent(room.servedBy._id));
		if (!agent) {
			throw new Error('invalid-agent');
		}

		return API.v1.success({ agent });
	},
});

API.v1.addRoute(
	'livechat/agent.next/:token',
	{ validateParams: isGETAgentNextToken },
	{
		async get() {
			const { token } = this.urlParams;
			const room = await findOpenRoom(token, undefined, this.userId);
			if (room) {
				return API.v1.success();
			}

			let { department } = this.queryParams;

View on GitHub (pinned to f9d3ec372b)

Solutions

Verify the agent user referenced in room.servedBy._id still exists in the Users collection.
Re-assign the livechat room to an active agent.
Check that the referenced user still has the livechat-agent role.

Defensive patterns

Strategy: try-catch

Try / catch

try {
  await getAgentInfo(rid, token);
} catch (e) {
  if (e.message === 'invalid-agent') {
    console.error('The assigned agent for this room no longer exists. Contact an admin to reassign the room.');
    // Optionally trigger a re-routing request
    return;
  }
  throw e;
}

Prevention

Monitor for deleted agents that still have livechat room assignments (servedBy references).
Run periodic data integrity checks between rooms.servedBy and the Users collection.
When deleting an agent, reassign or close their livechat rooms first.

When it happens

Trigger: A livechat room has servedBy._id set but the referenced agent user has been deleted, deactivated and removed from the livechat-agent role, or the user document is otherwise invalid for agent normalization.

Common situations: Agent user was deleted after the room was created; agent was removed from the livechat-agent role after assignment; data migration corrupted the servedBy reference.

Related errors

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