{"record":{"id":"5c7ec5e4017226d8","repo":"payloadcms/payload","slug":"field-field-label-has-reserved-name-fieldnam","errorCode":null,"errorMessage":"Field ${field.label} has reserved name '${fieldName}'.","messagePattern":"Field (.+?) has reserved name '(.+?)'\\.","errorType":"exception","errorClass":"ReservedFieldName","httpStatus":500,"severity":"error","filePath":"packages/payload/src/fields/config/sanitize.ts","lineNumber":184,"sourceCode":"\n  if (!field.type) {\n    throw new MissingFieldType(field)\n  }\n\n  const fieldAffectsData = _fieldAffectsData(field)\n\n  const { indexPath, schemaPath } = getFieldPaths({\n    field,\n    index,\n    parentIndexPath,\n    parentSchemaPath,\n  })\n\n  // Reserved field name checks\n  if (isTopLevelField && fieldAffectsData && field.name) {\n    if (collectionConfig && collectionConfig.upload) {\n      if (reservedBaseUploadFieldNames.includes(field.name)) {\n        throw new ReservedFieldName(field, field.name)\n      }\n    }\n\n    if (\n      collectionConfig &&\n      collectionConfig.auth &&\n      typeof collectionConfig.auth === 'object' &&\n      !collectionConfig.auth.disableLocalStrategy\n    ) {\n      if (reservedBaseAuthFieldNames.includes(field.name)) {\n        throw new ReservedFieldName(field, field.name)\n      }\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        }","sourceCodeStart":166,"sourceCodeEnd":202,"githubUrl":"https://github.com/payloadcms/payload/blob/00c58b35c0ed348ddc22daabf467b139727214fd/packages/payload/src/fields/config/sanitize.ts#L166-L202","documentation":"A top-level, data-affecting field in an upload-enabled collection (`collectionConfig.upload` set) reuses one of the names Payload reserves for upload metadata (reservedBaseUploadFieldNames, e.g. filename, mimeType, filesize, url, width, height, focalX, focalY). Payload auto-generates these columns on upload collections, so a user field with the same name would collide in the DB and in the admin UI.","triggerScenarios":"Collection with `upload: true` (or `upload: {...}`) plus a field like `{ name: 'filename', type: 'text' }` or `{ name: 'mimeType', type: 'select' }`.","commonSituations":"Building a Media/Assets collection and adding a descriptive field whose name happens to match a Payload upload field; migrating a custom upload setup into Payload's native upload and forgetting to rename existing columns.","solutions":["Rename the field to something not in `reservedBaseUploadFieldNames` (e.g. `displayName` instead of `filename`).","If you genuinely need to override upload behavior, configure it through `collectionConfig.upload` options, not a same-named field.","Audit the collection's fields list against the reserved list in `packages/payload/src/fields/config/reservedFieldNames.ts`."],"exampleFix":"// before\n{ slug: 'media', upload: true, fields: [\n  { name: 'filename', type: 'text' }\n]}\n// after\n{ slug: 'media', upload: true, fields: [\n  { name: 'displayName', type: 'text' }\n]}","handlingStrategy":"validation","validationCode":"// pseudocode — replicate the reserved list the sanitizer uses\nconst reservedBaseUploadFieldNames = ['filename','filesize','mimeType','url','width','height','focalX','focalY','thumbnailURL','sizes'] // verify against your Payload version\nfunction checkUploadReservedNames(collection) {\n  if (!collection.upload) return []\n  const clashes = collection.fields\n    .filter(f => f.name && reservedBaseUploadFieldNames.includes(f.name))\n    .map(f => f.name)\n  return clashes\n}\n// run for each upload collection before buildConfig()","typeGuard":"function isReservedUploadName(name: string, reserved: string[]): boolean {\n  return reserved.includes(name)\n}","tryCatchPattern":"try {\n  await payload.init({ config })\n} catch (err) {\n  if (err?.name === 'ReservedFieldName' || /reserved name/i.test(err?.message ?? '')) {\n    console.error('Reserved upload field name:', err?.data?.fieldName)\n  }\n  throw err\n}","preventionTips":["Keep upload collections' custom field names prefixed (e.g. `metaX`) to avoid collisions.","Maintain a project-level lint script that asserts collection field names against the reserved lists."],"tags":["upload","reserved-names","config","schema","sanitization"],"backgroundTag":null,"analyzedSha":"00c58b35c0ed348ddc22daabf467b139727214fd","analyzedAt":"2026-08-12T20:45:03.758Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}