{"record":{"id":"923493e7fb4994e5","repo":"RocketChat/Rocket.Chat","slug":"error-livechat-visitor-registration","errorCode":null,"errorMessage":"error-livechat-visitor-registration","messagePattern":"error-livechat-visitor-registration","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"apps/meteor/server/api/v1/omnichannel/message.ts","lineNumber":276,"sourceCode":"\t\t\tif (visitor) {\n\t\t\t\tconst extraQuery = await callbacks.run('livechat.applyRoomRestrictions', {}, { userId: this.userId });\n\t\t\t\tconst room = await LivechatRooms.findOneOpenByVisitorToken(visitorToken, { projection: { _id: 1 } }, extraQuery);\n\t\t\t\trid = room?._id ?? Random.id();\n\t\t\t} else {\n\t\t\t\trid = Random.id();\n\n\t\t\t\tconst guest: typeof this.bodyParams.visitor & { connectionData?: unknown } = this.bodyParams.visitor;\n\n\t\t\t\tif (settings.get('Livechat_Allow_collect_and_store_HTTP_header_informations')) {\n\t\t\t\t\tguest.connectionData = normalizeHttpHeaderData(this.request.headers);\n\t\t\t\t}\n\n\t\t\t\tvisitor = await registerGuest(guest, {\n\t\t\t\t\tshouldConsiderIdleAgent: settings.get<boolean>('Livechat_enabled_when_agent_idle'),\n\t\t\t\t\tshouldConsiderOfflineAgent: settings.get<boolean>('Livechat_accept_chats_with_no_agents'),\n\t\t\t\t});\n\t\t\t\tif (!visitor) {\n\t\t\t\t\tthrow new Error('error-livechat-visitor-registration');\n\t\t\t\t}\n\t\t\t}\n\n\t\t\tconst guest = visitor;\n\t\t\tif (!guest) {\n\t\t\t\tthrow new Error('error-invalid-token');\n\t\t\t}\n\n\t\t\tconst sentMessages = await Promise.all(\n\t\t\t\tthis.bodyParams.messages.map(async (message: { msg: string }): Promise<{ username: string; msg: string; ts: number }> => {\n\t\t\t\t\tconst messageToSend = {\n\t\t\t\t\t\tguest,\n\t\t\t\t\t\tmessage: {\n\t\t\t\t\t\t\t_id: Random.id(),\n\t\t\t\t\t\t\trid,\n\t\t\t\t\t\t\ttoken: visitorToken,\n\t\t\t\t\t\t\tmsg: message.msg,\n\t\t\t\t\t\t},","sourceCodeStart":258,"sourceCodeEnd":294,"githubUrl":"https://github.com/RocketChat/Rocket.Chat/blob/f9d3ec372bb580fa8d036f94cf03925a478ef768/apps/meteor/server/api/v1/omnichannel/message.ts#L258-L294","documentation":"Thrown in the POST handler of 'livechat/messages' (message.ts:271-277) when registerGuest() returns null. This path executes only when no existing visitor matches the provided visitorToken (LivechatVisitors.getVisitorByToken returns null at line 256). The system attempts to register a new guest via registerGuest from @rocket.chat/omni-core with agent availability settings. If registration fails (returns null/undefined), this error fires.","triggerScenarios":"Calling POST /api/v1/livechat/messages with a visitor.token that doesn't match any existing visitor, and the registration of a new guest fails. Registration can fail when no agents are available/online and the setting Livechat_accept_chats_with_no_agents is false, or when agent idle conditions prevent routing and Livechat_enabled_when_agent_idle is false.","commonSituations":"All omnichannel agents are offline and the system is configured to reject chats when no agents are available; agents are idle/busy and idle-agent rejection is enabled; department has no online agents; visitor data is incomplete and registration validation fails internally.","solutions":["Check agent availability — ensure at least one omnichannel agent is online and accepting chats.","Enable Livechat_accept_chats_with_no_agents setting if you want chats to queue when no agents are available.","Disable or adjust Livechat_enabled_when_agent_idle if idle agents are blocking registration.","Verify the visitor object in the request body includes all required fields for registration."],"exampleFix":"// before — registration fails when no agents available\nconst visitor = await registerGuest(guest, {\n  shouldConsiderIdleAgent: settings.get('Livechat_enabled_when_agent_idle'),\n  shouldConsiderOfflineAgent: settings.get('Livechat_accept_chats_with_no_agents'),\n});\n\n// after — ensure offline acceptance is enabled in admin settings\n// Admin > Omnichannel > Accept chats with no agents = true\n// Then retry the same POST request","handlingStrategy":"validation","validationCode":"// Check agent availability before attempting to send a message to a new visitor\nconst agentsOnline = await checkOnlineOmnichannelAgents();\nif (agentsOnline === 0 && !settings.get('Livechat_accept_chats_with_no_agents')) {\n  // either enable the setting or wait for agents to come online\n  throw new Error('No agents available — enable Livechat_accept_chats_with_no_agents or wait');\n}","typeGuard":null,"tryCatchPattern":"try {\n  await api.post('/livechat/messages', { visitor: { token, ...visitorData }, messages: [{ msg }] });\n} catch (err) {\n  if (err.message === 'error-livechat-visitor-registration') {\n    // check agent availability, adjust settings, or queue the message for retry\n    await waitForAgentAvailability();\n    await api.post('/livechat/messages', { visitor: { token, ...visitorData }, messages: [{ msg }] });\n  }\n}","preventionTips":["Ensure at least one omnichannel agent is online and available before sending messages for new visitors.","Enable Livechat_accept_chats_with_no_agents to allow chats to queue when no agents are available.","Disable Livechat_enabled_when_agent_idle if idle agents are blocking registration.","Validate that the visitor object includes all required fields (token, name, etc.) before sending."],"tags":["omnichannel","visitor-registration","agent-availability","configuration","messages"],"backgroundTag":null,"analyzedSha":"f9d3ec372bb580fa8d036f94cf03925a478ef768","analyzedAt":"2026-08-12T19:07:17.372Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}