RocketChat/Rocket.Chat · warning · Error

error-max-number-simultaneous-chats-reached

error-max-number-simultaneous-chats-reached

Error message

error-max-number-simultaneous-chats-reached

What it means

Thrown by the `beforeJoinRoom` omnichannel hook (MEDIUM priority, `livechat-before-join-room`) when an agent joining a livechat room would exceed configured chat limits. It is a plain `Error` with code-like message `error-max-number-simultaneous-chats-reached`. Limits come from the agent's per-agent cap, the global `Livechat_maximum_chats_per_agent` setting, and/or the department's `maxNumberSimultaneousChat`.

Source

Thrown at apps/meteor/ee/server/hooks/omnichannel/beforeJoinRoom.ts:30

		if (!settings.get('Livechat_waiting_queue')) {
			return user;
		}

		if (!room || !isOmnichannelRoom(room)) {
			return user;
		}
		const { departmentId } = room;
		const userSubs = await Users.getAgentAndAmountOngoingChats(user._id, departmentId);
		if (!userSubs) {
			return user;
		}
		const { queueInfo: { chats = 0, chatsForDepartment = 0 } = {} } = userSubs;

		if (await isAgentWithinChatLimits({ agentId: user._id, departmentId, totalChats: chats, departmentChats: chatsForDepartment })) {
			return user;
		}

		throw new Error('error-max-number-simultaneous-chats-reached');
	},
	callbacks.priority.MEDIUM,
	'livechat-before-join-room',
);

View on GitHub (pinned to f9d3ec372b)

Solutions

  1. Finish/close one of the agent's ongoing chats before joining another.
  2. Raise the per-agent `maxNumberSimultaneousChat`, the global setting, or the department's `maxNumberSimultaneousChat`.
  3. Route the conversation to another available agent via the queue.
Defensive patterns

Strategy: validation

Validate before calling

import { isAgentWithinChatLimits } from '../../lib/omnichannel/Helper';

async function agentCanJoin(user: { _id: string }, departmentId: string): Promise<boolean> {
	const userSubs = await Users.getAgentAndAmountOngoingChats(user._id, departmentId);
	if (!userSubs) return true;
	const { queueInfo: { chats = 0, chatsForDepartment = 0 } = {} } = userSubs;
	return isAgentWithinChatLimits({ agentId: user._id, departmentId, totalChats: chats, departmentChats: chatsForDepartment });
}

Type guard

function isMaxSimultaneousChatsError(e: unknown): boolean {
	return e instanceof Error && e.message === 'error-max-number-simultaneous-chats-reached';
}

Try / catch

try {
	await callbacks.run('beforeJoinRoom', user, room);
} catch (e) {
	if (e instanceof Error && e.message === 'error-max-number-simultaneous-chats-reached') {
		// route to another agent or raise the limit
	}
	throw e;
}

Prevention

When it happens

Trigger: An agent (livechat-managed user) joins a livechat room; `getAgentAndAmountOngoingChats` returns their current counts; `isAgentWithinChatLimits` returns false because total chats and/or department chats exceed the effective limit.

Common situations: Agent at their concurrent chat cap tries to take another conversation; department concurrency limit reached; global `Livechat_maximum_chats_per_agent` set low and agent is saturated.

Related errors

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