RocketChat/Rocket.Chat · error · Error

error-livechat-visitor-registration

Error message

error-livechat-visitor-registration

What it means

Thrown in the POST handler of 'livechat/messages' (message.ts:271-277) when registerGuest() returns null. This path executes only when no existing visitor matches the provided visitorToken (LivechatVisitors.getVisitorByToken returns null at line 256). The system attempts to register a new guest via registerGuest from @rocket.chat/omni-core with agent availability settings. If registration fails (returns null/undefined), this error fires.

Source

Thrown at apps/meteor/server/api/v1/omnichannel/message.ts:276

			if (visitor) {
				const extraQuery = await callbacks.run('livechat.applyRoomRestrictions', {}, { userId: this.userId });
				const room = await LivechatRooms.findOneOpenByVisitorToken(visitorToken, { projection: { _id: 1 } }, extraQuery);
				rid = room?._id ?? Random.id();
			} else {
				rid = Random.id();

				const guest: typeof this.bodyParams.visitor & { connectionData?: unknown } = this.bodyParams.visitor;

				if (settings.get('Livechat_Allow_collect_and_store_HTTP_header_informations')) {
					guest.connectionData = normalizeHttpHeaderData(this.request.headers);
				}

				visitor = await registerGuest(guest, {
					shouldConsiderIdleAgent: settings.get<boolean>('Livechat_enabled_when_agent_idle'),
					shouldConsiderOfflineAgent: settings.get<boolean>('Livechat_accept_chats_with_no_agents'),
				});
				if (!visitor) {
					throw new Error('error-livechat-visitor-registration');
				}
			}

			const guest = visitor;
			if (!guest) {
				throw new Error('error-invalid-token');
			}

			const sentMessages = await Promise.all(
				this.bodyParams.messages.map(async (message: { msg: string }): Promise<{ username: string; msg: string; ts: number }> => {
					const messageToSend = {
						guest,
						message: {
							_id: Random.id(),
							rid,
							token: visitorToken,
							msg: message.msg,
						},

View on GitHub (pinned to f9d3ec372b)

Solutions

  1. Check agent availability — ensure at least one omnichannel agent is online and accepting chats.
  2. Enable Livechat_accept_chats_with_no_agents setting if you want chats to queue when no agents are available.
  3. Disable or adjust Livechat_enabled_when_agent_idle if idle agents are blocking registration.
  4. Verify the visitor object in the request body includes all required fields for registration.

Example fix

// before — registration fails when no agents available
const visitor = await registerGuest(guest, {
  shouldConsiderIdleAgent: settings.get('Livechat_enabled_when_agent_idle'),
  shouldConsiderOfflineAgent: settings.get('Livechat_accept_chats_with_no_agents'),
});

// after — ensure offline acceptance is enabled in admin settings
// Admin > Omnichannel > Accept chats with no agents = true
// Then retry the same POST request
Defensive patterns

Strategy: validation

Validate before calling

// Check agent availability before attempting to send a message to a new visitor
const agentsOnline = await checkOnlineOmnichannelAgents();
if (agentsOnline === 0 && !settings.get('Livechat_accept_chats_with_no_agents')) {
  // either enable the setting or wait for agents to come online
  throw new Error('No agents available — enable Livechat_accept_chats_with_no_agents or wait');
}

Try / catch

try {
  await api.post('/livechat/messages', { visitor: { token, ...visitorData }, messages: [{ msg }] });
} catch (err) {
  if (err.message === 'error-livechat-visitor-registration') {
    // check agent availability, adjust settings, or queue the message for retry
    await waitForAgentAvailability();
    await api.post('/livechat/messages', { visitor: { token, ...visitorData }, messages: [{ msg }] });
  }
}

Prevention

When it happens

Trigger: Calling POST /api/v1/livechat/messages with a visitor.token that doesn't match any existing visitor, and the registration of a new guest fails. Registration can fail when no agents are available/online and the setting Livechat_accept_chats_with_no_agents is false, or when agent idle conditions prevent routing and Livechat_enabled_when_agent_idle is false.

Common situations: All omnichannel agents are offline and the system is configured to reject chats when no agents are available; agents are idle/busy and idle-agent rejection is enabled; department has no online agents; visitor data is incomplete and registration validation fails internally.

Related errors

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