{"record":{"id":"d444eb66dcb7a86b","repo":"RocketChat/Rocket.Chat","slug":"error-invalid-visitor-d444eb","errorCode":"error-invalid-visitor","errorMessage":"Invalid visitor","messagePattern":"Invalid visitor","errorType":"exception","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/f9d3ec372bb580fa8d036f94cf03925a478ef768/apps/meteor/server/api/v1/omnichannel/sms.ts#L64-L100","documentation":"Thrown by defineVisitor in the SMS-incoming handler when registerGuest returns null. registerGuest creates/refreshes a Livechat visitor from the parsed SMS payload; a null return means registration could not produce a usable visitor record (e.g. required fields missing, agent/department routing rejected, internal validation failure).","triggerScenarios":"POST livechat/sms-incoming/:service where registerGuest fails to upsert the visitor — empty/invalid SMS number, no department available and the offline/idle policy refuses the chat, or registerGuest internally returned null on a validation error.","commonSituations":"SMS_Default_Omnichannel_Department points to a disabled/nonexistent department and no agents are online with Livechat_accept_chats_with_no_agents=false; the SMS provider sends an empty fromNumber; visitor token collision; Livechat_enabled_when_agent_idle is off and the only agent is idle.","solutions":["Set a valid SMS_Default_Omnichannel_Department and ensure it has online agents or a routing fallback.","Enable Livechat_accept_chats_with_no_agents if SMS should still register when no agents are available.","Validate the incoming payload has a non-empty fromNumber before processing.","Inspect registerGuest's logs/code path for the specific null-return condition in your version."],"exampleFix":"// before\nconst visitor = await registerGuest(data, opts);\n\n// after\nconst visitor = await registerGuest(data, opts);\nif (!visitor) {\n  logger.warn('registerGuest returned null for SMS', { from: smsNumber, department: targetDepartment });\n  return API.v1.failure('Cannot register SMS visitor - check department/agent availability');\n}","handlingStrategy":"validation","validationCode":"if (!smsNumber || !smsNumber.trim()) throw new ClientError('empty-sms-from');\nconst dept = await LivechatDepartment.findOneByIdOrName(targetDepartment);\nif (!dept) throw new ClientError('no-default-department');\nconst onlineAgents = await countOnlineAgentsInDepartment(dept._id);\nif (onlineAgents === 0 && !settings.get('Livechat_accept_chats_with_no_agents')) throw new ClientError('no-agents');","typeGuard":"null","tryCatchPattern":"try {\n  await defineVisitor(smsNumber, dept);\n} catch (e) {\n  if (e.error === 'error-invalid-visitor') { logger.warn('registerGuest null', { smsNumber, dept }); return API.v1.failure('Cannot register SMS visitor'); }\n  throw e;\n}","preventionTips":["Configure a valid SMS_Default_Omnichannel_Department with online agents or a fallback.","Enable Livechat_accept_chats_with_no_agents if SMS should register regardless of agent presence.","Reject empty/malformed fromNumbers at the parser boundary."],"tags":["omnichannel","livechat","sms","visitor-registration","routing"],"backgroundTag":null,"analyzedSha":"f9d3ec372bb580fa8d036f94cf03925a478ef768","analyzedAt":"2026-08-12T19:07:17.372Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}