{"record":{"id":"e76d58a2fc4f1efb","repo":"payloadcms/payload","slug":"field-field-label-has-invalid-name-fieldname","errorCode":null,"errorMessage":"Field ${field.label} has invalid name '${fieldName}'. Field names can not include periods (.) and must be alphanumeric.","messagePattern":"Field (.+?) has invalid name '(.+?)'\\. Field names can not include periods \\(\\.\\) and must be alphanumeric\\.","errorType":"exception","errorClass":"InvalidFieldName","httpStatus":500,"severity":"error","filePath":"packages/payload/src/fields/config/sanitize.ts","lineNumber":214,"sourceCode":"      }\n\n      if (collectionConfig.auth.verify) {\n        // @ts-expect-error - vestiges of when tsconfig was not strict. Feel free to improve\n        if (reservedAPIKeyFieldNames.includes(field.name)) {\n          throw new ReservedFieldName(field, field.name)\n        }\n\n        // @ts-expect-error - vestiges of when tsconfig was not strict. Feel free to improve\n        if (reservedVerifyFieldNames.includes(field.name)) {\n          throw new ReservedFieldName(field, field.name)\n        }\n      }\n    }\n  }\n\n  // Invalid field name check\n  if (fieldAffectsData && field.name.includes('.')) {\n    throw new InvalidFieldName(field, field.name)\n  }\n\n  // Auto-label\n  if (\n    'name' in field &&\n    field.name &&\n    typeof field.label !== 'object' &&\n    typeof field.label !== 'string' &&\n    typeof field.label !== 'function' &&\n    field.label !== false\n  ) {\n    field.label = toWords(field.name)\n  }\n\n  // Checkbox default\n  if (\n    field.type === 'checkbox' &&\n    typeof field.defaultValue === 'undefined' &&","sourceCodeStart":196,"sourceCodeEnd":232,"githubUrl":"https://github.com/payloadcms/payload/blob/00c58b35c0ed348ddc22daabf467b139727214fd/packages/payload/src/fields/config/sanitize.ts#L196-L232","documentation":"A data-affecting field's `name` contains a period (`.`). Payload uses dots as path delimiters for nested fields, relationships, queries (`where.field=...`), and the admin form, so a literal dot in a name would create ambiguous paths. Names must be alphanumeric (no dots).","triggerScenarios":"Defining `{ name: 'user.email', type: 'text' }`, `{ name: 'meta.title', type: 'text' }`, or any field whose name includes a dot.","commonSituations":"Trying to namespace fields with dots to mimic nested paths; migrating from a system (e.g. some NoSQL setups) that allows dotted keys; auto-generating field names from dotted strings.","solutions":["Remove the dot from the name (use camelCase, snake_case, or a single token).","If you actually want nesting, model it as a `group` or `array` field with a child field of the second segment.","If you only need dotted access in queries, that is already supported via real nested fields — do not encode it in the name."],"exampleFix":"// before\n{ name: 'user.email', type: 'email' }\n// after\n{ name: 'userEmail', type: 'email' }\n// or model real nesting:\n{ name: 'user', type: 'group', fields: [\n  { name: 'email', type: 'email' }\n]}","handlingStrategy":"validation","validationCode":"function findDottedFieldNames(fields, path = '') {\n  const bad = []\n  for (const f of fields) {\n    if (typeof f?.name === 'string' && f.name.includes('.')) bad.push(`${path}${f.name}`)\n    if (Array.isArray(f?.fields)) bad.push(...findDottedFieldNames(f.fields, `${path}${f?.name}.`))\n  }\n  return bad\n}","typeGuard":"function isValidFieldName(name: unknown): name is string {\n  return typeof name === 'string' && name.length > 0 && !name.includes('.')\n}","tryCatchPattern":"try {\n  await payload.init({ config })\n} catch (err) {\n  if (err?.name === 'InvalidFieldName' || /invalid name/i.test(err?.message ?? '')) {\n    console.error('Field with invalid (dotted) name:', err?.data?.fieldName)\n  }\n  throw err\n}","preventionTips":["Use a regex lint: `^[A-Za-z][A-Za-z0-9_]*$` for field names.","When generating field names from data, strip or replace dots before use."],"tags":["field-name","config","schema","sanitization","query"],"backgroundTag":null,"analyzedSha":"00c58b35c0ed348ddc22daabf467b139727214fd","analyzedAt":"2026-08-12T20:45:03.758Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}