{"record":{"id":"258b70f58f8864c9","repo":"RocketChat/Rocket.Chat","slug":"invalid-visitor-cannot-create","errorCode":null,"errorMessage":"Invalid visitor, cannot create","messagePattern":"Invalid visitor, cannot create","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"apps/meteor/app/apps/server/bridges/livechat.ts","lineNumber":226,"sourceCode":"\n\t\tconst registerData = {\n\t\t\tdepartment: visitor.department,\n\t\t\tusername: visitor.username,\n\t\t\tname: visitor.name,\n\t\t\ttoken: visitor.token,\n\t\t\temail: '',\n\t\t\tid: visitor.id,\n\t\t\t...(visitor.phone?.length && { phone: { number: visitor.phone[0].phoneNumber } }),\n\t\t\t...(visitor.visitorEmails?.length && { email: visitor.visitorEmails[0].address }),\n\t\t};\n\n\t\tconst livechatVisitor = await registerGuest(registerData, {\n\t\t\tshouldConsiderIdleAgent: settings.get<boolean>('Livechat_enabled_when_agent_idle'),\n\t\t\tshouldConsiderOfflineAgent: settings.get<boolean>('Livechat_accept_chats_with_no_agents'),\n\t\t});\n\n\t\tif (!livechatVisitor) {\n\t\t\tthrow new Error('Invalid visitor, cannot create');\n\t\t}\n\n\t\treturn livechatVisitor._id;\n\t}\n\n\tprotected async createAndReturnVisitor(visitor: IVisitor, appId: string): Promise<IVisitor | undefined> {\n\t\tthis.orch.debugLog(`The App ${appId} is creating a livechat visitor.`);\n\n\t\t// Add appId to each externalId entry\n\t\tconst externalIds = visitor.externalIds?.map((entry) => ({ ...entry, appId }));\n\n\t\tconst registerData = {\n\t\t\tdepartment: visitor.department,\n\t\t\tusername: visitor.username,\n\t\t\tname: visitor.name,\n\t\t\ttoken: visitor.token,\n\t\t\temail: '',\n\t\t\tid: visitor.id,","sourceCodeStart":208,"sourceCodeEnd":244,"githubUrl":"https://github.com/RocketChat/Rocket.Chat/blob/f9d3ec372bb580fa8d036f94cf03925a478ef768/apps/meteor/app/apps/server/bridges/livechat.ts#L208-L244","documentation":"Thrown by the visitor creation path (createVisitor) when registerGuest from omni-core returns a falsy value. registerGuest is expected to either create or resolve a livechat visitor; a null/undefined result means guest registration failed (validation rejection, DB write failure, or duplicate resolution returning nothing), so the bridge cannot return a visitor id.","triggerScenarios":"An App calls the livechat creator to register a visitor; registerGuest(registerData, opts) resolves to null/undefined because the supplied visitor data fails server-side validation, the visitor could not be persisted, or the guest resolution pipeline returned an empty result.","commonSituations":"Visitor payload is missing required fields (token, name) that omni-core now enforces; Livechat_enabled_when_agent_idle / Livechat_accept_chats_with_no_agents settings produce a no-op registration; a unique-constraint conflict on token/email; transient DB error swallowed by registerGuest.","solutions":["Inspect the visitor payload passed to the creator and ensure required fields (token, optional name/email/phone) are well-formed.","Check the Livechat_enabled_when_agent_idle and Livechat_accept_chats_with_no_agents settings relative to current agent availability.","Verify the visitor token is not already registered with conflicting data (resolve the existing visitor first).","Wrap the create call and surface the underlying registerGuest failure rather than the generic bridge error."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// Validate required visitor fields before registration\nfunction buildRegisterData(visitor: IVisitor) {\n  if (!visitor.token) throw new Error('visitor.token is required');\n  return {\n    email: '',\n    id: visitor.id,\n    ...(visitor.phone?.length && { phone: { number: visitor.phone[0].phoneNumber } }),\n    ...(visitor.visitorEmails?.length && { email: visitor.visitorEmails[0].address }),\n  };\n}","typeGuard":"const isRegisterableVisitor = (v: IVisitor): boolean =>\n  Boolean(v.token && v.id);","tryCatchPattern":"try {\n  return await app.getLivechatCreator().createVisitor(visitor);\n} catch (e) {\n  if ((e as Error).message === 'Invalid visitor, cannot create') {\n    // log visitor payload, check agent-availability settings, dedupe by token\n  }\n  throw e;\n}","preventionTips":["Ensure visitor.token and visitor.id are set before registration.","Check Livechat_accept_chats_with_no_agents / Livechat_enabled_when_agent_idle settings.","Resolve an existing visitor by token before attempting to create a duplicate."],"tags":["apps-engine","livechat","visitor","registration","data-integrity"],"backgroundTag":null,"analyzedSha":"f9d3ec372bb580fa8d036f94cf03925a478ef768","analyzedAt":"2026-08-12T19:07:17.372Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}