RocketChat/Rocket.Chat · error · Error

error-invalid-custom-field-value

error-invalid-custom-field-value

Error message

error-invalid-custom-field-value

What it means

In validateCustomFields, a custom field marked required=true in the LivechatCustomField collection was entirely absent from the submitted customFields object. The thrown message is the translated 'error-invalid-custom-field-value' string with the field's label (or _id) interpolated. Absence of a required field is treated exactly like an invalid value.

Source

Thrown at apps/meteor/server/lib/omnichannel/contacts/validateCustomFields.ts:19

import type { AtLeast, ILivechatCustomField } from '@rocket.chat/core-typings';

import { i18n } from '../../../../app/utils/lib/i18n';
import { trim } from '../../../../lib/utils/stringUtils';

export function validateCustomFields(
	allowedCustomFields: AtLeast<ILivechatCustomField, '_id'>[],
	customFields: Record<string, string | unknown>,
	{
		ignoreAdditionalFields = false,
		ignoreValidationErrors = false,
	}: { ignoreAdditionalFields?: boolean; ignoreValidationErrors?: boolean } = {},
): Record<string, string> {
	const validValues: Record<string, string> = {};

	for (const cf of allowedCustomFields) {
		if (!customFields.hasOwnProperty(cf._id)) {
			if (cf.required && !ignoreValidationErrors) {
				throw new Error(i18n.t('error-invalid-custom-field-value', { field: cf.label || cf._id }));
			}
			continue;
		}
		const cfValue: string = trim(customFields[cf._id]);

		if (!cfValue || typeof cfValue !== 'string') {
			if (cf.required && !ignoreValidationErrors) {
				throw new Error(i18n.t('error-invalid-custom-field-value', { field: cf.label || cf._id }));
			}
			continue;
		}

		if (cf.regexp) {
			const regex = new RegExp(cf.regexp);
			if (!regex.test(cfValue)) {
				if (ignoreValidationErrors) {
					continue;
				}

View on GitHub (pinned to b2c16d5842)

Solutions

  1. List required fields (GET /api/v1/livechat/custom-fields and filter required) and include every one in the payload
  2. If the field should be optional, clear 'required' in the custom-field settings
  3. For import/best-effort flows, use a code path that passes ignoreValidationErrors: true to skip missing required fields

Example fix

// before
await registerContact({ token, email, customFields: { company: 'ACME' } }, userId); // 'address' is required

// after
await registerContact({ token, email, customFields: { company: 'ACME', address: '1 Main St' } }, userId);
Defensive patterns

Strategy: validation

Validate before calling

const fields = await LivechatCustomField.find({ scope: 'visitor' }).toArray();
const missing = fields.filter((f) => f.required && !(f._id in customFields));
if (missing.length) throw new Error(`Missing required custom fields: ${missing.map((f) => f._id).join(', ')}`);
await registerContact({ ...params, customFields }, userId);

Type guard

const hasAllRequired = (payload: Record<string, unknown>, required: string[]): payload is Record<string, string> =>
  required.every((id) => id in payload);

Try / catch

try {
  await registerContact(params, userId);
} catch (err) {
  if (err instanceof Error && err.message.includes('error-invalid-custom-field-value')) {
    // message names the field; add it to the payload or mark it optional in settings
  }
  throw err;
}

Prevention

When it happens

Trigger: Registering or updating a contact/visitor with a customFields payload that omits one or more fields flagged required in Administration > Omnichannel > Custom Fields (unless ignoreValidationErrors was passed true by the calling code path).

Common situations: A new required custom field was added after the client form was built; third-party webhook sends a fixed set of fields; client omits keys with empty values.

Related errors

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