{"record":{"id":"82672f215983ba48","repo":"RocketChat/Rocket.Chat","slug":"agent-not-found","errorCode":null,"errorMessage":"agent-not-found","messagePattern":"agent-not-found","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"warning","filePath":"apps/meteor/server/api/v1/omnichannel/agent.ts","lineNumber":66,"sourceCode":"\t{\n\t\tasync get() {\n\t\t\tconst { token } = this.urlParams;\n\t\t\tconst room = await findOpenRoom(token, undefined, this.userId);\n\t\t\tif (room) {\n\t\t\t\treturn API.v1.success();\n\t\t\t}\n\n\t\t\tlet { department } = this.queryParams;\n\t\t\tif (!department) {\n\t\t\t\tconst requireDepartment = await getRequiredDepartment();\n\t\t\t\tif (requireDepartment) {\n\t\t\t\t\tdepartment = requireDepartment._id;\n\t\t\t\t}\n\t\t\t}\n\n\t\t\tconst agentData = await RoutingManager.getNextAgent(department);\n\t\t\tif (!agentData) {\n\t\t\t\tthrow new Error('agent-not-found');\n\t\t\t}\n\n\t\t\tconst agent = await findAgent(agentData.agentId);\n\t\t\tif (!agent) {\n\t\t\t\tthrow new Error('invalid-agent');\n\t\t\t}\n\n\t\t\treturn API.v1.success({ agent });\n\t\t},\n\t},\n);\n\nAPI.v1.addRoute(\n\t'livechat/agent.status',\n\t{ authRequired: true, permissionsRequired: ['view-l-room'], validateParams: isPOSTLivechatAgentStatusProps },\n\t{\n\t\tasync post() {\n\t\t\tconst { status, agentId: inputAgentId } = this.bodyParams;","sourceCodeStart":48,"sourceCodeEnd":84,"githubUrl":"https://github.com/RocketChat/Rocket.Chat/blob/f9d3ec372bb580fa8d036f94cf03925a478ef768/apps/meteor/server/api/v1/omnichannel/agent.ts#L48-L84","documentation":"Thrown by GET /api/v1/livechat/agent.next/:token when RoutingManager.getNextAgent(department) returns null/falsy. The routing engine could not find any available agent to serve the next livechat conversation for the given department. This fires after confirming no open room already exists for the visitor.","triggerScenarios":"Requesting the next agent when all agents are offline or unavailable for the target department, when the department has no assigned agents, or when business hours are closed and no agents are on duty.","commonSituations":"All livechat agents offline outside business hours; department has no agents assigned; all agents are at maximum concurrent chat capacity; business hours are closed for the department; the department doesn't exist.","solutions":["Ensure at least one agent with the livechat-agent role is online and available for the department.","Verify agents are assigned to the target department in department settings.","Check that business hours are open (or configure after-hours fallback).","Verify RoutingManager configuration and agent status via the livechat agent status API."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// Check agent availability before requesting the next agent\nconst res = await fetch(`${baseUrl}/api/v1/livechat/agents.online?department=${department}`, {\n  headers: authHeaders\n}).then(r => r.json());\n\nif (!res.online || res.count === 0) {\n  throw new Error('No agents available — try again later or leave an offline message');\n}","typeGuard":null,"tryCatchPattern":"try {\n  await getNextAgent(token);\n} catch (e) {\n  if (e.message === 'agent-not-found') {\n    console.warn('No available agents. Showing offline form or queue position.');\n    return showOfflineForm();\n  }\n  throw e;\n}","preventionTips":["Check agent availability and business hours before requesting the next agent.","Provide an offline form fallback in the livechat widget when no agents are available.","Monitor agent staffing levels during peak hours."],"tags":["omnichannel","livechat","routing","agent","business-hours"],"backgroundTag":null,"analyzedSha":"f9d3ec372bb580fa8d036f94cf03925a478ef768","analyzedAt":"2026-08-12T19:07:17.372Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}