RocketChat/Rocket.Chat · error · 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 'livechat.checkAgentBeforeTakeInquiry' callback when an agent attempts to take an omnichannel inquiry but is already at or above a configured simultaneous-chat cap. The limit is computed in isAgentWithinChatLimits from three sources (in priority order): the agent's own livechat.maxNumberSimultaneousChat, the global Livechat_maximum_chats_per_agent setting, and the department's maxNumberSimultaneousChat. It is a plain Error (not a Meteor.Error), thrown only when Livechat_waiting_queue is enabled and the agent is not allowed to skip the queue.

Source

Thrown at apps/meteor/ee/server/hooks/omnichannel/checkAgentBeforeTakeInquiry.ts:62

	if (await allowAgentSkipQueue(agent)) {
		cbLogger.info({ msg: 'Chat can be taken by Agent: agent can skip queue', agentId });
		return agent;
	}

	const { department: departmentId } = inquiry;
	const user = await Users.getAgentAndAmountOngoingChats(agentId, departmentId);
	if (!user) {
		cbLogger.debug({ msg: 'No valid agent found', agentId });
		throw new Error('No valid agent found');
	}

	const { queueInfo: { chats = 0, chatsForDepartment = 0 } = {} } = user;

	if (await isAgentWithinChatLimits({ agentId, departmentId, totalChats: chats, departmentChats: chatsForDepartment })) {
		return user;
	}
	throw new Error('error-max-number-simultaneous-chats-reached');
};

callbacks.add('livechat.checkAgentBeforeTakeInquiry', validateMaxChats, callbacks.priority.MEDIUM, 'livechat-before-take-inquiry');

View on GitHub (pinned to f9d3ec372b)

Solutions

  1. Raise the per-agent limit (user.livechat.maxNumberSimultaneousChat), the global Livechat_maximum_chats_per_agent setting, or the department's maxNumberSimultaneousChat to fit expected load.
  2. Redistribute inquiries to other available agents, or let the inquiry stay in the queue until the agent's ongoing chats drop below the limit.
  3. If the agent should bypass the queue, grant the role/permission checked by allowAgentSkipQueue so the callback returns early.
  4. Disable Livechat_waiting_queue only if queueing is not desired (this changes routing behavior, not just the error).

Example fix

// before: agent always blocked at 5 chats
Livechat_maximum_chats_per_agent = 5

// after: raise to match staffing
Livechat_maximum_chats_per_agent = 10
Defensive patterns

Strategy: validation

Validate before calling

// Pre-check before taking an inquiry
import { isAgentWithinChatLimits } from '../../lib/omnichannel/Helper';
import { Users } from '@rocket.chat/models';

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

Type guard

const hasQueueInfo = (u: unknown): u is { queueInfo: { chats?: number; chatsForDepartment?: number } } =>
  typeof u === 'object' && u !== null && 'queueInfo' in (u as any);

Try / catch

try { await takeInquiry(...); } catch (e) {
  if (e instanceof Error && e.message === 'error-max-number-simultaneous-chats-reached') {
    // keep inquiry in queue; surface 'agent at capacity' to UI
  } else throw e;
}

Prevention

When it happens

Trigger: Agent accepts/takes a queued omnichannel inquiry while their ongoing chat count (total, or per-department) already meets the active limit; the request flows through the 'livechat.checkAgentBeforeTakeInquiry' callback (checkAgentBeforeTakeInquiry.ts:59). Only reached when settings.get('Livechat_waiting_queue') is truthy AND allowAgentSkipQueue(agent) returns false.

Common situations: Admin lowers Livechat_maximum_chats_per_agent or an agent's per-user maxNumberSimultaneousChat after agents already hold many chats; a department's maxNumberSimultaneousChat is set too low for current load; capacity planning mismatch during traffic spikes.

Related errors

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