{"record":{"id":"32f56929dc076b97","repo":"RocketChat/Rocket.Chat","slug":"error-forwarding-chat","errorCode":null,"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/b2c16d5842cbe6b69b59bdf6fc5e5f1afcd1f0b0/apps/meteor/server/api/v1/omnichannel/room.ts#L308-L344","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check server logs for the underlying reason logged around the failed transfer","Verify the target: agent exists, is online, and has the livechat agent role; department is enabled and staffed within business hours","Audit custom apps/callbacks that intercept transfers and make sure they return a success-shaped result","Retry the forward once state changes (agent back online) — transient races are common"],"exampleFix":null,"handlingStrategy":"retry","validationCode":"const agent = await getAgentInfo(targetId); // e.g. livechat/agent.info style lookup\nif (!agent?.online) { pickAnotherTarget(); return; }","typeGuard":"function isAgentAvailable(agent) {\n  return Boolean(agent) && agent.online === true && agent.status !== 'offline';\n}","tryCatchPattern":"try { await forward(roomId, payload); } catch (e) {\n  if (e.message === 'error-forwarding-chat') {\n    inspectServerLogs(); // root cause only visible server-side\n    return retryOnce(() => forward(roomId, { ...payload, userId: fallbackAgentId }));\n  }\n  throw e;\n}","preventionTips":["Verify the target agent is online and livechat-capable before offering the transfer","Keep transfers atomic in the UI (one in flight per room) to avoid races","Audit Apps-engine transfer callbacks when failures cluster"],"tags":["omnichannel","livechat","transfer","agent-availability","rest-api"],"backgroundTag":"chat-transfer-failed","analyzedSha":"b2c16d5842cbe6b69b59bdf6fc5e5f1afcd1f0b0","analyzedAt":"2026-08-18T15:26:39.429Z","contentChangedAt":"2026-08-18T15:26:39.429Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}