{"record":{"id":"32f56929dc076b97","repo":"RocketChat/Rocket.Chat","slug":"error-forwarding-chat","errorCode":"error-forwarding-chat","errorMessage":"error-forwarding-chat","messagePattern":"error-forwarding-chat","errorType":"exception","errorClass":"Error","httpStatus":400,"severity":"error","filePath":"apps/meteor/server/api/v1/omnichannel/room.ts","lineNumber":326,"sourceCode":"\t\t\tif (!guest) {\n\t\t\t\tthrow new Error('error-invalid-visitor');\n\t\t\t}\n\n\t\t\ttransferData.transferredBy = normalizeTransferredByData(this.user, room);\n\t\t\tif (transferData.userId) {\n\t\t\t\tconst userToTransfer = await Users.findOneById(transferData.userId);\n\t\t\t\tif (userToTransfer) {\n\t\t\t\t\ttransferData.transferredTo = {\n\t\t\t\t\t\t_id: userToTransfer._id,\n\t\t\t\t\t\tusername: userToTransfer.username,\n\t\t\t\t\t\tname: userToTransfer.name,\n\t\t\t\t\t};\n\t\t\t\t}\n\t\t\t}\n\n\t\t\tconst chatForwardedResult = await transfer(room, guest, transferData);\n\t\t\tif (!chatForwardedResult) {\n\t\t\t\tthrow new Error('error-forwarding-chat');\n\t\t\t}\n\n\t\t\treturn API.v1.success();\n\t\t},\n\t},\n);\n\nconst livechatVisitorDepartmentTransfer = API.v1.post(\n\t'livechat/visitor/department.transfer',\n\t{\n\t\tresponse: {\n\t\t\t200: ajv.compile<void>({\n\t\t\t\ttype: 'object',\n\t\t\t\tproperties: {\n\t\t\t\t\tsuccess: {\n\t\t\t\t\t\ttype: 'boolean',\n\t\t\t\t\t\tenum: [true],\n\t\t\t\t\t},","sourceCodeStart":308,"sourceCodeEnd":344,"githubUrl":"https://github.com/RocketChat/Rocket.Chat/blob/f9d3ec372bb580fa8d036f94cf03925a478ef768/apps/meteor/server/api/v1/omnichannel/room.ts#L308-L344","documentation":"Thrown by POST livechat/room.forward when the transfer(room, guest, transferData) helper returns a falsy result. The transfer helper can fail to route because the target department has no online agents, the target user is invalid, or internal routing rejects the move. This is a downstream failure after all preconditions passed.","triggerScenarios":"POST livechat/room.forward where transfer() returns null/false: target department offline with no fallback, target userId references a non-agent or disabled user, or the routing callback aborted the transfer.","commonSituations":"Department has no online agents and Livechat_accept_chats_with_no_agents is false; transferredTo.userId resolves to a user without the livechat-agent role; a callback in the transfer pipeline (e.g. livechat.transfer') blocked the move; transient race where the room was closed between the open-check and transfer().","solutions":["Confirm the target agent is online, has the livechat-agent role, and belongs to the target department.","Enable Livechat_accept_chats_with_no_agents or configure department fallback if the department is frequently empty.","Inspect server logs around the transfer() call for the specific internal reason it returned falsy.","Retry after correcting the target; if it still fails, transfer to a queue/department instead of a specific user."],"exampleFix":"// before\nawait POST('/api/v1/livechat/room.forward', { roomId, userId: targetId });\n\n// after\nif (!await isAgentOnlineAndInDepartment(targetId, departmentId)) {\n  await POST('/api/v1/livechat/room.forward', { roomId, departmentId }); // queue to dept\n} else {\n  await POST('/api/v1/livechat/room.forward', { roomId, userId: targetId });\n}","handlingStrategy":"try-catch","validationCode":"const agent = await Users.findOneById(targetUserId);\nif (!agent || !agent.roles?.includes('livechat-agent')) throw new ClientError('target-not-agent');\nif (!await isAgentOnlineInDepartment(targetUserId, departmentId)) throw new ClientError('target-unavailable');","typeGuard":"null","tryCatchPattern":"try {\n  await POST('/api/v1/livechat/room.forward', { roomId, userId });\n} catch (e) {\n  if (e.message === 'error-forwarding-chat') {\n    logTransferFailure(roomId, targetUserId);\n    await POST('/api/v1/livechat/room.forward', { roomId, departmentId }); // fallback to dept queue\n    return;\n  }\n  throw e;\n}","preventionTips":["Validate target agent online status and department membership before offering them as a transfer target.","Enable department fallback / Livechat_accept_chats_with_no_agents if direct transfers frequently fail.","Log transfer() internals so the falsy return has an attributable cause."],"tags":["omnichannel","livechat","transfer","routing","agent-availability"],"backgroundTag":null,"analyzedSha":"f9d3ec372bb580fa8d036f94cf03925a478ef768","analyzedAt":"2026-08-12T19:07:17.372Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}