RocketChat/Rocket.Chat · warning · Error

agent-not-found

Error message

agent-not-found

What it means

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.

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 f9d3ec372b)

Solutions

1. Ensure at least one agent with the livechat-agent role is online and available for the department.
2. Verify agents are assigned to the target department in department settings.
3. Check that business hours are open (or configure after-hours fallback).
4. Verify RoutingManager configuration and agent status via the livechat agent status API.

// Check agent availability before requesting the next agent
const res = await fetch(`${baseUrl}/api/v1/livechat/agents.online?department=${department}`, {
  headers: authHeaders
}).then(r => r.json());

if (!res.online || res.count === 0) {
  throw new Error('No agents available — try again later or leave an offline message');
}

try {
  await getNextAgent(token);
} catch (e) {
  if (e.message === 'agent-not-found') {
    console.warn('No available agents. Showing offline form or queue position.');
    return showOfflineForm();
  }
  throw e;
}

When it happens

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

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

Related errors

• invalid-agent
• error-forwarding-chat
• error-invalid-visitor
• The agent with id "${agent.id}" was not found.
• Invalid agentId

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