{"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":400,"severity":"error","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/b2c16d5842cbe6b69b59bdf6fc5e5f1afcd1f0b0/apps/meteor/server/api/v1/omnichannel/agent.ts#L48-L84","documentation":"GET /api/v1/livechat/agent.next/:token throws 'agent-not-found' when RoutingManager.getNextAgent(department) returns null. getNextAgent applies the configured routing method over the currently available agents of the resolved department (explicit query param, otherwise the required/default department); null means no agent is available to take the chat right now.","triggerScenarios":"Calling livechat/agent.next for a token with no open room while every omnichannel agent (or every agent in the resolved department) is offline or statusLivechat=NOT_AVAILABLE; a workspace with zero livechat agents; a department with no enabled agents; business hours closed so nobody counts as available.","commonSituations":"New install with omnichannel enabled but no agents added or none toggled 'Available'; agents forgetting to switch omnichannel status after login; business-hours window excluding the request time; department agents all disabled after an org change.","solutions":["Ensure at least one user is added as an omnichannel agent and is available: POST /api/v1/livechat/agent.status with { \"status\": \"available\" } as that agent.","If a department is required (or passed as ?department=), confirm that department has enabled, available agents (Omnichannel > Departments).","If business hours are the cause, widen the hours or configure the offline form so visitors get the offline flow instead of the error.","Verify the routing method setting (Omnichannel > Routing) still yields candidates; test with Auto-Selection to rule out a custom/external bureau returning nothing."],"exampleFix":"// before: no agent online -> agent-not-found\nawait fetch(`/api/v1/livechat/agent.next/${token}`);\n\n// after: agent makes themselves available first\nawait fetch('/api/v1/livechat/agent.status', {\n  method: 'POST',\n  headers,\n  body: JSON.stringify({ status: 'available' }),\n});\nconst res = await fetch(`/api/v1/livechat/agent.next/${token}`);","handlingStrategy":"fallback","validationCode":"// Check availability before requesting the next agent\nconst { agents } = await get('/api/v1/livechat/agents', { status: 'available' });\nif (!agents?.length) {\n  return showOfflineForm(token); // graceful path instead of agent-not-found\n}\nconst { agent } = await get(`/api/v1/livechat/agent.next/${token}`);","typeGuard":null,"tryCatchPattern":"try { agent = await getNextAgent(token); } catch (e) { if (e.message === 'agent-not-found') return offlineFlow(); throw e; }","preventionTips":["Keep at least one agent available during business hours; page on-call when availability drops to zero.","Monitor business-hours windows so the offline form is shown proactively.","Verify each department has enabled, available agents after org changes."],"tags":["omnichannel","livechat","agent-routing","queue","rest-api"],"backgroundTag":"service-unavailable","analyzedSha":"b2c16d5842cbe6b69b59bdf6fc5e5f1afcd1f0b0","analyzedAt":"2026-08-18T15:26:39.429Z","contentChangedAt":"2026-08-18T15:26:39.429Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}