RocketChat/Rocket.Chat · error · Meteor.Error

error-livechat-visitor-registration

error-livechat-visitor-registration

Error message

Error registering visitor

What it means

Thrown by POST /api/v1/livechat/visitor when registerGuest() returns null, i.e. the visitor upsert (packages/omni-core/src/visitor/create.ts:106) completed without returning a document. Distinguish it from registerGuest's own throws: an empty token throws error-invalid-token, an unknown department throws error-invalid-department, and an invalid email throws from validateEmail — those surface as different errors. This error-livechat-visitor-registration specifically means the database write did not yield the visitor back.

Solutions

1. Check server logs (Livechat - Visitor logger, debug level shows the upsert path) for the underlying Mongo error
2. Retry the registration once — transient write failures are the most common cause
3. Sanitize the payload anyway: non-empty token, valid department id/name, valid email format, to rule out the adjacent thrown errors
4. Verify Mongo health and that no unique index (token/username) is rejecting the write

// cheap pre-flight to rule out registerGuest's thrown variants first
if (!payload.visitor?.token?.trim()) throw new Error('token required');
if (payload.visitor.email && !/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(payload.visitor.email)) throw new Error('bad email');
if (payload.visitor.department) await assertDepartmentExists(payload.visitor.department);

try {
  const body = await registerVisitor(payload);
  if (!body.success && body.error === 'Error registering visitor') return retryWithBackoff(payload, 2); // DB-side upsert failure
} catch (e) { /* network vs 400 body handling */ }

When it happens

Trigger: POST /api/v1/livechat/visitor with a valid token but during Mongo instability (write fails / returns no document); concurrent registrations for the same token where a unique-index conflict aborts the upsert; database permission changes preventing upserts on the visitors collection.

Common situations: Widget registrations failing during DB maintenance windows; load tests hammering the same token; after restoring a backup where visitor indexes are stale.

Related errors

• error-invalid-token
• invalid-token
• error-importer-not-defined
• error-invalid-visitor
• error-removing-visitor

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

Appendix: source

Thrown at apps/meteor/server/api/v1/omnichannel/visitor.ts:67

			const guest = {
				token,
				...(id && { id }),
				...(name && { name }),
				...(email && { email }),
				...(department && { department }),
				...(username && { username }),
				...(connectionData && { connectionData }),
				...(phone && typeof phone === 'string' && { phone: { number: phone as string } }),
				connectionData: normalizeHttpHeaderData(this.request.headers),
			};

			const 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 Meteor.Error('error-livechat-visitor-registration', 'Error registering visitor', {
					method: 'livechat/visitor',
				});
			}

			const extraQuery = await callbacks.run('livechat.applyRoomRestrictions', {}, { userId: this.userId });
			// If it's updating an existing visitor, it must also update the roomInfo
			const rooms = await LivechatRooms.findOpenByVisitorToken(visitor?.token, {}, extraQuery).toArray();
			await Promise.all(
				rooms.map(
					(room: IRoom) =>
						visitor &&
						saveRoomInfo(room, {
							_id: visitor._id,
							name: visitor.name,
							phone: visitor.phone?.[0]?.phoneNumber,
							livechatData: visitor.livechatData as { [k: string]: string },
						}),
				),

View on GitHub (pinned to b2c16d5842)