RocketChat/Rocket.Chat · error · Meteor.Error

error-invalid-visitor

error-invalid-visitor

Error message

Invalid visitor

What it means

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).

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 f9d3ec372b)

Solutions

1. Set a valid SMS_Default_Omnichannel_Department and ensure it has online agents or a routing fallback.
2. Enable Livechat_accept_chats_with_no_agents if SMS should still register when no agents are available.
3. Validate the incoming payload has a non-empty fromNumber before processing.
4. Inspect registerGuest's logs/code path for the specific null-return condition in your version.

Example fix

// before
const visitor = await registerGuest(data, opts);

// after
const visitor = await registerGuest(data, opts);
if (!visitor) {
  logger.warn('registerGuest returned null for SMS', { from: smsNumber, department: targetDepartment });
  return API.v1.failure('Cannot register SMS visitor - check department/agent availability');
}

if (!smsNumber || !smsNumber.trim()) throw new ClientError('empty-sms-from');
const dept = await LivechatDepartment.findOneByIdOrName(targetDepartment);
if (!dept) throw new ClientError('no-default-department');
const onlineAgents = await countOnlineAgentsInDepartment(dept._id);
if (onlineAgents === 0 && !settings.get('Livechat_accept_chats_with_no_agents')) throw new ClientError('no-agents');

null

try {
  await defineVisitor(smsNumber, dept);
} catch (e) {
  if (e.error === 'error-invalid-visitor') { logger.warn('registerGuest null', { smsNumber, dept }); return API.v1.failure('Cannot register SMS visitor'); }
  throw e;
}

When it happens

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

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

Related errors

• agent-not-found
• error-forwarding-chat
• error-invalid-file-uploaded
• error-contact-not-found
• error-visitor-not-found

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