{"record":{"id":"2e57de5e604b461a","repo":"RocketChat/Rocket.Chat","slug":"error-max-number-simultaneous-chats-reached-2e57de","errorCode":"error-max-number-simultaneous-chats-reached","errorMessage":"error-max-number-simultaneous-chats-reached","messagePattern":"error-max-number-simultaneous-chats-reached","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"apps/meteor/ee/server/hooks/omnichannel/checkAgentBeforeTakeInquiry.ts","lineNumber":62,"sourceCode":"\n\tif (await allowAgentSkipQueue(agent)) {\n\t\tcbLogger.info({ msg: 'Chat can be taken by Agent: agent can skip queue', agentId });\n\t\treturn agent;\n\t}\n\n\tconst { department: departmentId } = inquiry;\n\tconst user = await Users.getAgentAndAmountOngoingChats(agentId, departmentId);\n\tif (!user) {\n\t\tcbLogger.debug({ msg: 'No valid agent found', agentId });\n\t\tthrow new Error('No valid agent found');\n\t}\n\n\tconst { queueInfo: { chats = 0, chatsForDepartment = 0 } = {} } = user;\n\n\tif (await isAgentWithinChatLimits({ agentId, departmentId, totalChats: chats, departmentChats: chatsForDepartment })) {\n\t\treturn user;\n\t}\n\tthrow new Error('error-max-number-simultaneous-chats-reached');\n};\n\ncallbacks.add('livechat.checkAgentBeforeTakeInquiry', validateMaxChats, callbacks.priority.MEDIUM, 'livechat-before-take-inquiry');\n","sourceCodeStart":44,"sourceCodeEnd":66,"githubUrl":"https://github.com/RocketChat/Rocket.Chat/blob/f9d3ec372bb580fa8d036f94cf03925a478ef768/apps/meteor/ee/server/hooks/omnichannel/checkAgentBeforeTakeInquiry.ts#L44-L66","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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.","Redistribute inquiries to other available agents, or let the inquiry stay in the queue until the agent's ongoing chats drop below the limit.","If the agent should bypass the queue, grant the role/permission checked by allowAgentSkipQueue so the callback returns early.","Disable Livechat_waiting_queue only if queueing is not desired (this changes routing behavior, not just the error)."],"exampleFix":"// before: agent always blocked at 5 chats\nLivechat_maximum_chats_per_agent = 5\n\n// after: raise to match staffing\nLivechat_maximum_chats_per_agent = 10","handlingStrategy":"validation","validationCode":"// Pre-check before taking an inquiry\nimport { isAgentWithinChatLimits } from '../../lib/omnichannel/Helper';\nimport { Users } from '@rocket.chat/models';\n\nasync function canAgentTake(agentId: string, departmentId?: string): Promise<boolean> {\n  const user = await Users.getAgentAndAmountOngoingChats(agentId, departmentId);\n  if (!user) return false;\n  const { chats = 0, chatsForDepartment = 0 } = user.queueInfo ?? {};\n  return isAgentWithinChatLimits({ agentId, departmentId, totalChats: chats, departmentChats: chatsForDepartment });\n}","typeGuard":"const hasQueueInfo = (u: unknown): u is { queueInfo: { chats?: number; chatsForDepartment?: number } } =>\n  typeof u === 'object' && u !== null && 'queueInfo' in (u as any);","tryCatchPattern":"try { await takeInquiry(...); } catch (e) {\n  if (e instanceof Error && e.message === 'error-max-number-simultaneous-chats-reached') {\n    // keep inquiry in queue; surface 'agent at capacity' to UI\n  } else throw e;\n}","preventionTips":["Size Livechat_maximum_chats_per_agent and per-department limits to actual staffing.","Surface ongoing-chat counts in the agent UI so agents self-throttle.","Grant queue-skip only to roles that should bypass the limit."],"tags":["omnichannel","livechat","queue","capacity","enterprise"],"backgroundTag":null,"analyzedSha":"f9d3ec372bb580fa8d036f94cf03925a478ef768","analyzedAt":"2026-08-12T19:07:17.372Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}