What causes "Invalid visitor" in RocketChat/Rocket.Chat?

Inspect server logs (SMS logger and 'Livechat - Visitor' debug logs) for the real upsert failure

RocketChat/Rocket.Chat · error · Meteor.Error

error-invalid-visitor

error-invalid-visitor

Error message

Invalid visitor

What it means

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.

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

Defensive patterns

Strategy: retry

Try / catch

// SMS provider side: respond 5xx so the provider re-delivers the webhook
try {
  await deliverInboundSms(payload);
} catch (e: any) {
  if (e?.error === 'error-invalid-visitor' || e?.reason === 'Invalid visitor') {
    return res.status(503).send('retry later'); // transient visitor-upsert failure
  }
  throw e;
}

Prevention

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

When it happens

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

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

Related errors

AI-assisted analysis of RocketChat/Rocket.Chat@b2c16d5842 (2026-08-18). Data as JSON: /api/errors/d444eb66dcb7a86b. Report an issue: GitHub.

Appendix: source

Thrown at apps/meteor/server/api/v1/omnichannel/sms.ts:82

		data = Object.assign(data, {
			username: smsNumber.replace(/[^0-9]/g, ''),
			phone: {
				number: smsNumber,
			},
		});
	}

	if (targetDepartment) {
		data.department = targetDepartment;
	}

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

	if (!livechatVisitor) {
		throw new Meteor.Error('error-invalid-visitor', 'Invalid visitor');
	}

	return livechatVisitor;
};

const normalizeLocationSharing = (payload: ServiceData) => {
	const { extra: { fromLatitude: latitude, fromLongitude: longitude } = {} } = payload;
	if (!latitude || !longitude) {
		return;
	}

	return {
		type: 'Point',
		coordinates: [parseFloat(longitude), parseFloat(latitude)],
	};
};

// @ts-expect-error - this is an special endpoint that requires the return to not be wrapped as regular returns

View on GitHub (pinned to b2c16d5842)