RocketChat/Rocket.Chat · error · Error

invalid-setting

Error message

invalid-setting

What it means

Thrown by the livechat appearance settings endpoint when one or more submitted setting _id values are not in the hardcoded validSettingList whitelist (approximately 25 known Livechat_* / Omnichannel_* appearance settings). The endpoint validates every submitted setting _id against this list before writing to the database.

Source

Thrown at apps/meteor/server/api/v1/omnichannel/appearance.ts:62

				'Livechat_offline_email',
				'Livechat_conversation_finished_message',
				'Livechat_conversation_finished_text',
				'Livechat_registration_form',
				'Livechat_name_field_registration_form',
				'Livechat_email_field_registration_form',
				'Livechat_registration_form_message',
				'Livechat_hide_watermark',
				'Livechat_background',
				'Livechat_widget_position',
				'Livechat_hide_system_messages',
				'Omnichannel_allow_visitors_to_close_conversation',
				'Livechat_hide_expand_chat',
			];

			const valid = settings.every((setting) => validSettingList.includes(setting._id));

			if (!valid) {
				throw new Error('invalid-setting');
			}

			const dbSettings = await Settings.findByIds(validSettingList, { projection: { _id: 1, value: 1, type: 1, values: 1 } })
				.map((dbSetting) => {
					const setting = settings.find(({ _id }) => _id === dbSetting._id);
					if (!setting || dbSetting.value === setting.value) {
						return;
					}

					if (dbSetting.type === 'multiSelect' && (!Array.isArray(setting.value) || !validateValues(setting.value, dbSetting.values))) {
						return;
					}

					switch (dbSetting?.type) {
						case 'boolean':
							return {
								_id: dbSetting._id,
								value: setting.value === 'true' || setting.value === true,

View on GitHub (pinned to f9d3ec372b)

Solutions

1. Cross-reference the submitted setting _id values against the validSettingList array defined in apps/meteor/server/api/v1/omnichannel/appearance.ts.
2. Remove the invalid setting _id from the request payload.
3. Use the correct endpoint (e.g., PUT /api/v1/settings/:_id) for settings not in the appearance whitelist.

Example fix

// before: includes a non-whitelisted setting
PUT /api/v1/livechat/appearance
{
  "settings": [
    { "_id": "Livechat_title", "value": "My Chat" },
    { "_id": "SMTP_Host", "value": "smtp.local" }
  ]
}
// after: only whitelisted appearance settings
PUT /api/v1/livechat/appearance
{
  "settings": [
    { "_id": "Livechat_title", "value": "My Chat" }
  ]
}

// Validate all setting _id values against the known whitelist before submitting
const VALID_LIVECHAT_APPEARANCE_SETTINGS = [
  'Livechat_title', 'Livechat_title_color', 'Livechat_enable_message_character_limit',
  'Livechat_message_character_limit', 'Livechat_show_agent_info', 'Livechat_show_agent_email',
  'Livechat_display_offline_form', 'Livechat_offline_form_unavailable', 'Livechat_offline_message',
  'Livechat_offline_success_message', 'Livechat_offline_title', 'Livechat_offline_title_color',
  'Livechat_offline_email', 'Livechat_conversation_finished_message', 'Livechat_conversation_finished_text',
  'Livechat_registration_form', 'Livechat_name_field_registration_form', 'Livechat_email_field_registration_form',
  'Livechat_registration_form_message', 'Livechat_hide_watermark', 'Livechat_background',
  'Livechat_widget_position', 'Livechat_hide_system_messages',
  'Omnichannel_allow_visitors_to_close_conversation', 'Livechat_hide_expand_chat',
];

function filterValidSettings(settings) {
  return settings.filter(s => VALID_LIVECHAT_APPEARANCE_SETTINGS.includes(s._id));
}

const validSettings = filterValidSettings(submittedSettings);
if (validSettings.length !== submittedSettings.length) {
  console.warn('Some settings were filtered out — not in the appearance whitelist');
}

function isValidAppearanceSettingId(id: string): boolean {
  const valid = new Set([
    'Livechat_title', 'Livechat_title_color', 'Livechat_enable_message_character_limit',
    'Livechat_message_character_limit', 'Livechat_show_agent_info', 'Livechat_show_agent_email',
    'Livechat_display_offline_form', 'Livechat_offline_form_unavailable', 'Livechat_offline_message',
    'Livechat_offline_success_message', 'Livechat_offline_title', 'Livechat_offline_title_color',
    'Livechat_offline_email', 'Livechat_conversation_finished_message', 'Livechat_conversation_finished_text',
    'Livechat_registration_form', 'Livechat_name_field_registration_form', 'Livechat_email_field_registration_form',
    'Livechat_registration_form_message', 'Livechat_hide_watermark', 'Livechat_background',
    'Livechat_widget_position', 'Livechat_hide_system_messages',
    'Omnichannel_allow_visitors_to_close_conversation', 'Livechat_hide_expand_chat',
  ]);
  return valid.has(id);
}

try {
  await updateLivechatAppearance(settings);
} catch (e) {
  if (e.message === 'invalid-setting') {
    console.error('One or more setting IDs are not in the appearance whitelist.');
    console.error('Valid IDs:', VALID_LIVECHAT_APPEARANCE_SETTINGS);
    return;
  }
  throw e;
}

When it happens

Trigger: Submitting an appearance update that includes a setting _id not in the validSettingList array — either a typo, a renamed setting from a version upgrade, or an attempt to modify a non-appearance setting through this endpoint.

Common situations: Frontend sends a setting ID that was renamed or removed in a Rocket.Chat version upgrade; typo in the setting name in the request payload; client attempts to set a non-appearance setting (e.g., a server-level setting) through the appearance endpoint.

Related errors

• error-invalid-sla
• error-forwarding-department-target-not-allowed
• error-invalid-sla
• error-invalid-priority
• error-invalid-sla

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