RocketChat/Rocket.Chat · error

error-user-not-belong-to-department

error-user-not-belong-to-department

Error message

error-user-not-belong-to-department

What it means

When forwarding to department+agent, LivechatDepartmentAgents.findOneByAgentIdAndDepartmentId must find the agent inside the target department; otherwise it throws error-user-not-belong-to-department. It fires after the online check, so the agent exists and is online but is not assigned to the destination department.

Source

Thrown at apps/meteor/server/lib/omnichannel/Helper.ts:678

			msg: 'Forwarding room to department and user',
			roomId: room._id,
			departmentId,
			agentId,
		});
		const user = await Users.findOneOnlineAgentById(
			agentId,
			settings.get<boolean>('Livechat_enabled_when_agent_idle'),
			settings.get<boolean>('Livechat_accept_chats_with_no_agents'),
			{},
		);
		if (!user) {
			throw new Error('error-user-is-offline');
		}
		const isInDepartment = await LivechatDepartmentAgents.findOneByAgentIdAndDepartmentId(agentId, departmentId, {
			projection: { _id: 1 },
		});
		if (!isInDepartment) {
			throw new Error('error-user-not-belong-to-department');
		}
		const { username } = user;
		agent = { agentId, username };
	}

	const department = await LivechatDepartment.findOneById<
		Pick<ILivechatDepartment, 'allowReceiveForwardOffline' | 'fallbackForwardDepartment' | 'name'>
	>(departmentId, {
		projection: {
			allowReceiveForwardOffline: 1,
			fallbackForwardDepartment: 1,
			name: 1,
		},
	});

	// Cases:
	// 1. Routing is manual
	// 2. Server is out of macs

View on GitHub (pinned to b2c16d5842)

Solutions

  1. Choose an agent assigned to the target department (Omnichannel -> Departments -> agents)
  2. Add the agent to the department first, then retry the forward
  3. UI: filter the agent picker by the selected department

Example fix

// before
await forwardRoomToDepartment(room, { departmentId, userId: anyOnlineAgent._id }, guest);

// after
const inDept = await LivechatDepartmentAgents.findOneByAgentIdAndDepartmentId(agentId, departmentId, { projection: { _id: 1 } });
if (!inDept) throw new Error('error-user-not-belong-to-department');
await forwardRoomToDepartment(room, { departmentId, userId: agentId }, guest);
Defensive patterns

Strategy: validation

Validate before calling

const inDept = await LivechatDepartmentAgents.findOneByAgentIdAndDepartmentId(agentId, departmentId, {
  projection: { _id: 1 },
});
if (!inDept) {
  // pick an agent who belongs to the target department
}

Try / catch

try {
  await forwardRoomToDepartment(room, transferData, guest);
} catch (err) {
  if (err instanceof Error && err.message === 'error-user-not-belong-to-department') {
    // add the agent to the department or choose a member agent, then retry
  } else throw err;
}

Prevention

When it happens

Trigger: Forward payload pairs the userId of an agent never added to that department, or removed from it after a reorg; department membership changed concurrently with the transfer.

Common situations: New agents not yet added to departments; admin removed an agent from the department; agent pickers listing agents across all departments without filtering by the chosen target.

Related errors

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