{"record":{"id":"d444eb66dcb7a86b","repo":"RocketChat/Rocket.Chat","slug":"error-invalid-visitor-d444eb","errorCode":"error-invalid-visitor","errorMessage":"Invalid visitor","messagePattern":"Invalid visitor","errorType":"error_code","errorClass":"Meteor.Error","httpStatus":400,"severity":"error","filePath":"apps/meteor/server/api/v1/omnichannel/sms.ts","lineNumber":82,"sourceCode":"\t\tdata = Object.assign(data, {\n\t\t\tusername: smsNumber.replace(/[^0-9]/g, ''),\n\t\t\tphone: {\n\t\t\t\tnumber: smsNumber,\n\t\t\t},\n\t\t});\n\t}\n\n\tif (targetDepartment) {\n\t\tdata.department = targetDepartment;\n\t}\n\n\tconst livechatVisitor = await registerGuest(data, {\n\t\tshouldConsiderIdleAgent: settings.get<boolean>('Livechat_enabled_when_agent_idle'),\n\t\tshouldConsiderOfflineAgent: settings.get<boolean>('Livechat_accept_chats_with_no_agents'),\n\t});\n\n\tif (!livechatVisitor) {\n\t\tthrow new Meteor.Error('error-invalid-visitor', 'Invalid visitor');\n\t}\n\n\treturn livechatVisitor;\n};\n\nconst normalizeLocationSharing = (payload: ServiceData) => {\n\tconst { extra: { fromLatitude: latitude, fromLongitude: longitude } = {} } = payload;\n\tif (!latitude || !longitude) {\n\t\treturn;\n\t}\n\n\treturn {\n\t\ttype: 'Point',\n\t\tcoordinates: [parseFloat(longitude), parseFloat(latitude)],\n\t};\n};\n\n// @ts-expect-error - this is an special endpoint that requires the return to not be wrapped as regular returns","sourceCodeStart":64,"sourceCodeEnd":100,"githubUrl":"https://github.com/RocketChat/Rocket.Chat/blob/b2c16d5842cbe6b69b59bdf6fc5e5f1afcd1f0b0/apps/meteor/server/api/v1/omnichannel/sms.ts#L64-L100","documentation":"Thrown by the inbound SMS webhook (POST /api/v1/livechat/sms-incoming/:service) when registerGuest() returns null while creating or updating the visitor record derived from the sender's phone number. registerGuest (packages/omni-core/src/visitor/create.ts) only returns null when the Mongo upsert of the visitor document fails to return a document; bad input such as an invalid token or department raises different errors. So this error almost always means the visitor upsert against MongoDB failed or returned nothing.","triggerScenarios":"Inbound SMS arrives, defineVisitor() looks up/creates the visitor by phone number, and LivechatVisitors.updateOneByIdOrToken(..., { upsert: true, returnDocument: 'after' }) yields no document — e.g. during a Mongo replica-set step-down, a failed write, or a write-concern timeout.","commonSituations":"Database instability under load; Mongo elections mid-webhook; a visitor document that violates a unique index (e.g. conflicting token/username) making the upsert fail. Distinct from user error: bad department or phone data raises error-invalid-department or similar, not this.","solutions":["Inspect server logs (SMS logger and 'Livechat - Visitor' debug logs) for the real upsert failure","Have the SMS provider retry the webhook — transient Mongo issues usually clear","Check MongoDB health, replica set status, and disk space on the database host","Look for duplicate-key errors on visitors' token/username indexes and repair the conflicting document"],"exampleFix":null,"handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"// SMS provider side: respond 5xx so the provider re-delivers the webhook\ntry {\n  await deliverInboundSms(payload);\n} catch (e: any) {\n  if (e?.error === 'error-invalid-visitor' || e?.reason === 'Invalid visitor') {\n    return res.status(503).send('retry later'); // transient visitor-upsert failure\n  }\n  throw e;\n}","preventionTips":["Return a retryable status (503) to SMS providers when visitor upsert fails so they re-post","Keep Mongo healthy and monitored — this error is almost always a DB write failure","Alert on repeat failures for the same phone number to detect index conflicts"],"tags":["sms","omnichannel","visitor","mongodb","webhook"],"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"}