RocketChat/Rocket.Chat · error · Error

error-mac-limit-reached

error-mac-limit-reached

Error message

error-mac-limit-reached

What it means

Thrown by POST livechat/room.forward when Omnichannel.isWithinMACLimit(room) returns false. MAC (Maximum Active Conversations) caps how many simultaneous open Livechat rooms an agent can serve; the check runs on the destination/transfer context. Forwarding is refused when the receiving agent would exceed their configured MAC.

Source

Thrown at apps/meteor/server/api/v1/omnichannel/room.ts:304

	{ authRequired: true, permissionsRequired: ['view-l-room', 'transfer-livechat-guest'], validateParams: isLiveChatRoomForwardProps },
	{
		async post() {
			const transferData = this.bodyParams as typeof this.bodyParams & {
				transferredBy: TransferByData;
				transferredTo?: { _id: string; username?: string; name?: string };
			};

			const room = await LivechatRooms.findOneById(this.bodyParams.roomId);
			if (room?.t !== 'l') {
				throw new Error('error-invalid-room');
			}

			if (!room.open) {
				throw new Error('This_conversation_is_already_closed');
			}

			if (!(await Omnichannel.isWithinMACLimit(room))) {
				throw new Error('error-mac-limit-reached');
			}

			const guest = await LivechatVisitors.findOneEnabledById(room.v?._id);
			if (!guest) {
				throw new Error('error-invalid-visitor');
			}

			transferData.transferredBy = normalizeTransferredByData(this.user, room);
			if (transferData.userId) {
				const userToTransfer = await Users.findOneById(transferData.userId);
				if (userToTransfer) {
					transferData.transferredTo = {
						_id: userToTransfer._id,
						username: userToTransfer.username,
						name: userToTransfer.name,
					};
				}
			}

View on GitHub (pinned to f9d3ec372b)

Solutions

1. Transfer to a different agent or department whose open conversation count is under their MAC limit.
2. Raise the Livechat_maximum_chats_per_agent setting (Admin > Omnichannel) if the cap is too restrictive.
3. Queue the transfer instead of forcing it (use department transfer with queueing enabled).
4. Check current load via livechat/analytics or agents endpoint before offering the transfer target in the UI.

Example fix

// before
await POST('/api/v1/livechat/room.forward', { roomId, userId: targetId });

// after
const load = await GET('/api/v1/livechat/analytics/agent-overview', { name: 'Chats', departmentId });
if (load[targetId]?.open >= macLimit) {
  suggestAlternativeAgent();
} else {
  await POST('/api/v1/livechat/room.forward', { roomId, userId: targetId });
}

const macLimit = settings.get('Livechat_maximum_chats_per_agent');
const openCount = await LivechatRooms.countOpenByAgent(targetUserId);
if (macLimit && openCount >= macLimit) throw new ClientError('target-at-mac');

null

try {
  await POST('/api/v1/livechat/room.forward', { roomId, userId });
} catch (e) {
  if (e.message === 'error-mac-limit-reached') { offerAlternativeAgents(); return; }
  throw e;
}

When it happens

Trigger: POST livechat/room.forward where the transfer target (userId/department) already holds >= their MAC limit of open conversations. Also fires if the system-wide Livechat_maximum_chats_per_agent is low and the room count is at the ceiling.

Common situations: Transferring to a busy agent during peak load; department-level MAC set lower than expected after an admin policy change; auto-routing queued the agent to capacity before the manual forward; misconfigured Livechat_maximum_chats_per_agent (0 or unset behaving as unlimited vs a numeric cap).

Related errors

• error-max-number-simultaneous-chats-reached
• error-invalid-visitor
• error-forwarding-chat
• Invalid visitor, cannot transfer
• Invalid app user, cannot transfer

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