RocketChat/Rocket.Chat · error · Error

Invalid visitor, cannot create

Error message

Invalid visitor, cannot create

What it means

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.

Source

Thrown at apps/meteor/app/apps/server/bridges/livechat.ts:226

		const registerData = {
			department: visitor.department,
			username: visitor.username,
			name: visitor.name,
			token: visitor.token,
			email: '',
			id: visitor.id,
			...(visitor.phone?.length && { phone: { number: visitor.phone[0].phoneNumber } }),
			...(visitor.visitorEmails?.length && { email: visitor.visitorEmails[0].address }),
		};

		const livechatVisitor = await registerGuest(registerData, {
			shouldConsiderIdleAgent: settings.get<boolean>('Livechat_enabled_when_agent_idle'),
			shouldConsiderOfflineAgent: settings.get<boolean>('Livechat_accept_chats_with_no_agents'),
		});

		if (!livechatVisitor) {
			throw new Error('Invalid visitor, cannot create');
		}

		return livechatVisitor._id;
	}

	protected async createAndReturnVisitor(visitor: IVisitor, appId: string): Promise<IVisitor | undefined> {
		this.orch.debugLog(`The App ${appId} is creating a livechat visitor.`);

		// Add appId to each externalId entry
		const externalIds = visitor.externalIds?.map((entry) => ({ ...entry, appId }));

		const registerData = {
			department: visitor.department,
			username: visitor.username,
			name: visitor.name,
			token: visitor.token,
			email: '',
			id: visitor.id,

View on GitHub (pinned to f9d3ec372b)

Solutions

1. Inspect the visitor payload passed to the creator and ensure required fields (token, optional name/email/phone) are well-formed.
2. Check the Livechat_enabled_when_agent_idle and Livechat_accept_chats_with_no_agents settings relative to current agent availability.
3. Verify the visitor token is not already registered with conflicting data (resolve the existing visitor first).
4. Wrap the create call and surface the underlying registerGuest failure rather than the generic bridge error.

// Validate required visitor fields before registration
function buildRegisterData(visitor: IVisitor) {
  if (!visitor.token) throw new Error('visitor.token is required');
  return {
    email: '',
    id: visitor.id,
    ...(visitor.phone?.length && { phone: { number: visitor.phone[0].phoneNumber } }),
    ...(visitor.visitorEmails?.length && { email: visitor.visitorEmails[0].address }),
  };
}

const isRegisterableVisitor = (v: IVisitor): boolean =>
  Boolean(v.token && v.id);

try {
  return await app.getLivechatCreator().createVisitor(visitor);
} catch (e) {
  if ((e as Error).message === 'Invalid visitor, cannot create') {
    // log visitor payload, check agent-availability settings, dedupe by token
  }
  throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Room with id ${transferData.room} not found
• Transfer to entity with id ${transferData.to} not found
• Visitor with id ${visitorId} not found
• Room with id ${roomId} not found
• Department ${departmentData._id} not found

AI-assisted analysis of RocketChat/Rocket.Chat@f9d3ec372b (2026-08-12). Data as JSON: /api/errors/258b70f58f8864c9. Report an issue: GitHub.