{"record":{"id":"26c313af38d184f8","repo":"RocketChat/Rocket.Chat","slug":"error-livechat-visitor-registration-26c313","errorCode":"error-livechat-visitor-registration","errorMessage":"Error registering visitor","messagePattern":"Error registering visitor","errorType":"exception","errorClass":"Meteor.Error","httpStatus":400,"severity":"error","filePath":"apps/meteor/server/api/v1/omnichannel/visitor.ts","lineNumber":67,"sourceCode":"\n\t\t\tconst guest = {\n\t\t\t\ttoken,\n\t\t\t\t...(id && { id }),\n\t\t\t\t...(name && { name }),\n\t\t\t\t...(email && { email }),\n\t\t\t\t...(department && { department }),\n\t\t\t\t...(username && { username }),\n\t\t\t\t...(connectionData && { connectionData }),\n\t\t\t\t...(phone && typeof phone === 'string' && { phone: { number: phone as string } }),\n\t\t\t\tconnectionData: normalizeHttpHeaderData(this.request.headers),\n\t\t\t};\n\n\t\t\tconst visitor = await registerGuest(guest, {\n\t\t\t\tshouldConsiderIdleAgent: settings.get<boolean>('Livechat_enabled_when_agent_idle'),\n\t\t\t\tshouldConsiderOfflineAgent: settings.get<boolean>('Livechat_accept_chats_with_no_agents'),\n\t\t\t});\n\t\t\tif (!visitor) {\n\t\t\t\tthrow new Meteor.Error('error-livechat-visitor-registration', 'Error registering visitor', {\n\t\t\t\t\tmethod: 'livechat/visitor',\n\t\t\t\t});\n\t\t\t}\n\n\t\t\tconst extraQuery = await callbacks.run('livechat.applyRoomRestrictions', {}, { userId: this.userId });\n\t\t\t// If it's updating an existing visitor, it must also update the roomInfo\n\t\t\tconst rooms = await LivechatRooms.findOpenByVisitorToken(visitor?.token, {}, extraQuery).toArray();\n\t\t\tawait Promise.all(\n\t\t\t\trooms.map(\n\t\t\t\t\t(room: IRoom) =>\n\t\t\t\t\t\tvisitor &&\n\t\t\t\t\t\tsaveRoomInfo(room, {\n\t\t\t\t\t\t\t_id: visitor._id,\n\t\t\t\t\t\t\tname: visitor.name,\n\t\t\t\t\t\t\tphone: visitor.phone?.[0]?.phoneNumber,\n\t\t\t\t\t\t\tlivechatData: visitor.livechatData as { [k: string]: string },\n\t\t\t\t\t\t}),\n\t\t\t\t),","sourceCodeStart":49,"sourceCodeEnd":85,"githubUrl":"https://github.com/RocketChat/Rocket.Chat/blob/f9d3ec372bb580fa8d036f94cf03925a478ef768/apps/meteor/server/api/v1/omnichannel/visitor.ts#L49-L85","documentation":"Thrown as Meteor.Error('error-livechat-visitor-registration', 'Error registering visitor') when registerGuest returns null. registerGuest returns null only when LivechatVisitors.updateOneByIdOrToken with upsert+returnDocument:'after' yields no document - i.e. the upsert matched nothing and the insertion did not produce a returned document (a persistence/index failure path).","triggerScenarios":"POST livechat/visitor with a token that survives the empty-check but the visitor upsert does not return a document - for example a duplicate-key error on a unique index during upsert, an invalid department causing the upstream error-invalid-department to be thrown by registerGuest (different path), or a transient DB write failure swallowed into a null return.","commonSituations":"Concurrent visitor registration racing on the same token causing a unique index conflict; Mongo write transaction aborted; corrupted visitor document referenced by token/id.","solutions":["Retry the registration once with the same token (races are often transient).","Inspect server logs for Mongo duplicate-key or write errors around the failure time.","Validate the department field (if supplied) resolves to a real department, since registerGuest throws error-invalid-department for unknown departments.","If reproducible, check LivechatVisitors collection indexes and the document for the given token."],"exampleFix":"null","handlingStrategy":"retry","validationCode":"null","typeGuard":"null","tryCatchPattern":"try {\n  await registerVisitor();\n} catch (e) {\n  if (e.error === 'error-livechat-visitor-registration') {\n    // wait briefly and retry once; races on the same token often clear\n    await new Promise(r => setTimeout(r, 200));\n    await registerVisitor();\n  } else throw e;\n}","preventionTips":["Avoid concurrent register calls for the same visitor token from multiple tabs/widgets.","Inspect server logs for the underlying Mongo error if the retry fails.","Validate department field client-side to avoid registerGuest's error-invalid-department path."],"tags":["omnichannel","visitor","registration","database","upsert"],"backgroundTag":null,"analyzedSha":"f9d3ec372bb580fa8d036f94cf03925a478ef768","analyzedAt":"2026-08-12T19:07:17.372Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}