{"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/b2c16d5842cbe6b69b59bdf6fc5e5f1afcd1f0b0/apps/meteor/server/api/v1/omnichannel/visitor.ts#L49-L85","documentation":"Thrown by POST /api/v1/livechat/visitor when registerGuest() returns null, i.e. the visitor upsert (packages/omni-core/src/visitor/create.ts:106) completed without returning a document. Distinguish it from registerGuest's own throws: an empty token throws error-invalid-token, an unknown department throws error-invalid-department, and an invalid email throws from validateEmail — those surface as different errors. This error-livechat-visitor-registration specifically means the database write did not yield the visitor back.","triggerScenarios":"POST /api/v1/livechat/visitor with a valid token but during Mongo instability (write fails / returns no document); concurrent registrations for the same token where a unique-index conflict aborts the upsert; database permission changes preventing upserts on the visitors collection.","commonSituations":"Widget registrations failing during DB maintenance windows; load tests hammering the same token; after restoring a backup where visitor indexes are stale.","solutions":["Check server logs (Livechat - Visitor logger, debug level shows the upsert path) for the underlying Mongo error","Retry the registration once — transient write failures are the most common cause","Sanitize the payload anyway: non-empty token, valid department id/name, valid email format, to rule out the adjacent thrown errors","Verify Mongo health and that no unique index (token/username) is rejecting the write"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// cheap pre-flight to rule out registerGuest's thrown variants first\nif (!payload.visitor?.token?.trim()) throw new Error('token required');\nif (payload.visitor.email && !/^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$/.test(payload.visitor.email)) throw new Error('bad email');\nif (payload.visitor.department) await assertDepartmentExists(payload.visitor.department);","typeGuard":null,"tryCatchPattern":"try {\n  const body = await registerVisitor(payload);\n  if (!body.success && body.error === 'Error registering visitor') return retryWithBackoff(payload, 2); // DB-side upsert failure\n} catch (e) { /* network vs 400 body handling */ }","preventionTips":["Sanitize token/email/department client-side to eliminate the deterministic throws","Retry once or twice with backoff — a null upsert is usually transient","Watch server 'Livechat - Visitor' debug logs when this recurs"],"tags":["livechat-widget","visitor","rest-api","mongodb","registration"],"backgroundTag":"visitor-registration-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"}