RocketChat/Rocket.Chat · error · Error

agent-not-found

Error message

agent-not-found

What it means

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.

Solutions

1. 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.
2. If a department is required (or passed as ?department=), confirm that department has enabled, available agents (Omnichannel > Departments).
3. If business hours are the cause, widen the hours or configure the offline form so visitors get the offline flow instead of the error.
4. Verify the routing method setting (Omnichannel > Routing) still yields candidates; test with Auto-Selection to rule out a custom/external bureau returning nothing.

Example fix

// before: no agent online -> agent-not-found
await fetch(`/api/v1/livechat/agent.next/${token}`);

// after: agent makes themselves available first
await fetch('/api/v1/livechat/agent.status', {
  method: 'POST',
  headers,
  body: JSON.stringify({ status: 'available' }),
});
const res = await fetch(`/api/v1/livechat/agent.next/${token}`);

// Check availability before requesting the next agent
const { agents } = await get('/api/v1/livechat/agents', { status: 'available' });
if (!agents?.length) {
  return showOfflineForm(token); // graceful path instead of agent-not-found
}
const { agent } = await get(`/api/v1/livechat/agent.next/${token}`);

try { agent = await getNextAgent(token); } catch (e) { if (e.message === 'agent-not-found') return offlineFlow(); throw e; }

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• error-forwarding-chat
• error-invalid-department-unit
• error-invalid-room
• error-invalid-user
• error-invalid-visitor

AI-assisted analysis of RocketChat/Rocket.Chat@b2c16d5842 (2026-08-18). Data as JSON: /api/errors/82672f215983ba48. Report an issue: GitHub.

Appendix: source

Thrown at apps/meteor/server/api/v1/omnichannel/agent.ts:66

	{
		async get() {
			const { token } = this.urlParams;
			const room = await findOpenRoom(token, undefined, this.userId);
			if (room) {
				return API.v1.success();
			}

			let { department } = this.queryParams;
			if (!department) {
				const requireDepartment = await getRequiredDepartment();
				if (requireDepartment) {
					department = requireDepartment._id;
				}
			}

			const agentData = await RoutingManager.getNextAgent(department);
			if (!agentData) {
				throw new Error('agent-not-found');
			}

			const agent = await findAgent(agentData.agentId);
			if (!agent) {
				throw new Error('invalid-agent');
			}

			return API.v1.success({ agent });
		},
	},
);

API.v1.addRoute(
	'livechat/agent.status',
	{ authRequired: true, permissionsRequired: ['view-l-room'], validateParams: isPOSTLivechatAgentStatusProps },
	{
		async post() {
			const { status, agentId: inputAgentId } = this.bodyParams;

View on GitHub (pinned to b2c16d5842)