RocketChat/Rocket.Chat · error · Error

error-forwarding-chat

Error message

error-forwarding-chat

What it means

Thrown by POST /api/v1/livechat/room.forward when the transfer(room, guest, transferData) service returns a falsy result — the actual hand-off (to agent, department, or queue) failed internally. All preconditions passed; this is the transfer engine itself refusing or failing, and the reason is only visible in server logs.

Solutions

1. Check server logs for the underlying reason logged around the failed transfer
2. Verify the target: agent exists, is online, and has the livechat agent role; department is enabled and staffed within business hours
3. Audit custom apps/callbacks that intercept transfers and make sure they return a success-shaped result
4. Retry the forward once state changes (agent back online) — transient races are common

const agent = await getAgentInfo(targetId); // e.g. livechat/agent.info style lookup
if (!agent?.online) { pickAnotherTarget(); return; }

function isAgentAvailable(agent) {
  return Boolean(agent) && agent.online === true && agent.status !== 'offline';
}

try { await forward(roomId, payload); } catch (e) {
  if (e.message === 'error-forwarding-chat') {
    inspectServerLogs(); // root cause only visible server-side
    return retryOnce(() => forward(roomId, { ...payload, userId: fallbackAgentId }));
  }
  throw e;
}

When it happens

Trigger: Target agent is offline/has no livechat-agent role at execution time; target department has no available agents or does not accept the transfer; transfer callbacks ('livechat:transferHandler' style hooks, custom apps listening to transfer events) returned failure; internal errors while creating the new inquiry.

Common situations: Custom Apps-engine handlers vetoing transfers; agent goes offline between selection and execution; departments whose business hours closed in the meantime; edge cases in return values of the transfer service after upgrades.

Related errors

• error-invalid-room
• error-invalid-visitor
• agent-not-found
• error-forwarding-chat-same-department
• error-invalid-agent

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

Appendix: source

Thrown at apps/meteor/server/api/v1/omnichannel/room.ts:326

			if (!guest) {
				throw new Error('error-invalid-visitor');
			}

			transferData.transferredBy = normalizeTransferredByData(this.user, room);
			if (transferData.userId) {
				const userToTransfer = await Users.findOneById(transferData.userId);
				if (userToTransfer) {
					transferData.transferredTo = {
						_id: userToTransfer._id,
						username: userToTransfer.username,
						name: userToTransfer.name,
					};
				}
			}

			const chatForwardedResult = await transfer(room, guest, transferData);
			if (!chatForwardedResult) {
				throw new Error('error-forwarding-chat');
			}

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

const livechatVisitorDepartmentTransfer = API.v1.post(
	'livechat/visitor/department.transfer',
	{
		response: {
			200: ajv.compile<void>({
				type: 'object',
				properties: {
					success: {
						type: 'boolean',
						enum: [true],
					},

View on GitHub (pinned to b2c16d5842)