{"record":{"id":"3f91e4ccf8c113ab","repo":"RocketChat/Rocket.Chat","slug":"invalid-custom-field","errorCode":"invalid-custom-field","errorMessage":"invalid-custom-field","messagePattern":"invalid-custom-field","errorType":"error_code","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"apps/meteor/server/lib/omnichannel/custom-fields.ts","lineNumber":66,"sourceCode":"\tawait LivechatContacts.updateById(contact._id, { $set: contactCustomFieldsToUpdate });\n}\n\nexport async function setCustomFields({\n\ttoken,\n\tkey,\n\tvalue,\n\toverwrite,\n}: {\n\tkey: string;\n\tvalue: string;\n\toverwrite: boolean;\n\ttoken: string;\n}): Promise<number> {\n\tlivechatLogger.debug({ msg: 'Setting custom fields data for visitor with token', token });\n\n\tconst customField = await LivechatCustomField.findOneById(key);\n\tif (!customField) {\n\t\tthrow new Error('invalid-custom-field');\n\t}\n\n\tif (customField.regexp !== undefined && customField.regexp !== '') {\n\t\tconst regexp = new RegExp(customField.regexp);\n\t\tif (!regexp.test(value)) {\n\t\t\tthrow new Error(i18n.t('error-invalid-custom-field-value', { field: key }));\n\t\t}\n\t}\n\n\tlet result;\n\tif (customField.scope === 'room') {\n\t\tresult = await LivechatRooms.updateDataByToken(token, key, value, overwrite);\n\t} else {\n\t\tresult = await LivechatVisitors.updateLivechatDataByToken(token, key, value, overwrite);\n\n\t\tconst visitor = await LivechatVisitors.getVisitorByToken(token, { projection: { _id: 1 } });\n\t\tif (visitor) {\n\t\t\tconst contacts = await LivechatContacts.findAllByVisitorId(visitor._id).toArray();","sourceCodeStart":48,"sourceCodeEnd":84,"githubUrl":"https://github.com/RocketChat/Rocket.Chat/blob/b2c16d5842cbe6b69b59bdf6fc5e5f1afcd1f0b0/apps/meteor/server/lib/omnichannel/custom-fields.ts#L48-L84","documentation":"In setCustomFields (POST /api/v1/omnichannel/custom-field / livechat custom-field route), LivechatCustomField.findOneById(key) returned null: the field definition you are writing to does not exist. Rocket.Chat only stores values for fields that are defined in the custom-field registry, so an undefined key is rejected before any visitor/room data is touched.","triggerScenarios":"POST /livechat/custom-field with a key that is not the exact _id of a defined custom field — typo, wrong case, using the field's label instead of its id, or the field was deleted.","commonSituations":"Field created in one environment (staging) but not in the target; field deleted during cleanup while widgets still submit it; client sends human label ('Company') instead of the id ('company').","solutions":["Create the field first: Administration > Omnichannel > Custom Fields, or POST /api/v1/livechat/custom-fields","Use the exact field _id (case-sensitive) — verify against GET /api/v1/livechat/custom-fields","If the field was deleted intentionally, stop sending it from the widget/integration"],"exampleFix":"// before\nawait POST('/api/v1/livechat/custom-field', { token, key: 'Company', value: 'ACME', overwrite: true }); // field id is 'company'\n\n// after\nawait POST('/api/v1/livechat/custom-field', { token, key: 'company', value: 'ACME', overwrite: true });","handlingStrategy":"validation","validationCode":"const definition = await LivechatCustomField.findOneById(key);\nif (!definition) throw new Error(`Custom field '${key}' is not defined; create it first`);\nawait setCustomFields({ token, key, value, overwrite });","typeGuard":"const isDefinedCustomFieldKey = (key: string, defined: Set<string>): boolean => defined.has(key);","tryCatchPattern":"try {\n  await setCustomFields({ token, key, value, overwrite });\n} catch (err) {\n  if (err instanceof Error && err.message === 'invalid-custom-field') {\n    // key is not a defined field id: create the field or fix the key, then retry\n  }\n  throw err;\n}","preventionTips":["Provision custom fields via API as part of deployment, per environment","Use exact field ids (case-sensitive), never labels","Return 4xx with a clear message from your own API when the key is undefined"],"tags":["omnichannel","livechat","custom-fields","not-found","validation"],"backgroundTag":"custom-field-not-defined","analyzedSha":"b2c16d5842cbe6b69b59bdf6fc5e5f1afcd1f0b0","analyzedAt":"2026-08-18T15:26:39.429Z","schemaVersion":2},"datasetVersion":"2026-08-21T13:17:26.733Z"}