payloadcms/payload · error · ReservedFieldName

Field ${field.label} has reserved name '${fieldName}'.

Error message

Field ${field.label} has reserved name '${fieldName}'.

What it means

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.

Source

Thrown at packages/payload/src/fields/config/sanitize.ts:184

  if (!field.type) {
    throw new MissingFieldType(field)
  }

  const fieldAffectsData = _fieldAffectsData(field)

  const { indexPath, schemaPath } = getFieldPaths({
    field,
    index,
    parentIndexPath,
    parentSchemaPath,
  })

  // Reserved field name checks
  if (isTopLevelField && fieldAffectsData && field.name) {
    if (collectionConfig && collectionConfig.upload) {
      if (reservedBaseUploadFieldNames.includes(field.name)) {
        throw new ReservedFieldName(field, field.name)
      }
    }

    if (
      collectionConfig &&
      collectionConfig.auth &&
      typeof collectionConfig.auth === 'object' &&
      !collectionConfig.auth.disableLocalStrategy
    ) {
      if (reservedBaseAuthFieldNames.includes(field.name)) {
        throw new ReservedFieldName(field, field.name)
      }

      if (collectionConfig.auth.verify) {
        // @ts-expect-error - vestiges of when tsconfig was not strict. Feel free to improve
        if (reservedAPIKeyFieldNames.includes(field.name)) {
          throw new ReservedFieldName(field, field.name)
        }

View on GitHub (pinned to 00c58b35c0)

Solutions

1. Rename the field to something not in `reservedBaseUploadFieldNames` (e.g. `displayName` instead of `filename`).
2. If you genuinely need to override upload behavior, configure it through `collectionConfig.upload` options, not a same-named field.
3. Audit the collection's fields list against the reserved list in `packages/payload/src/fields/config/reservedFieldNames.ts`.

Example fix

// before
{ slug: 'media', upload: true, fields: [
  { name: 'filename', type: 'text' }
]}
// after
{ slug: 'media', upload: true, fields: [
  { name: 'displayName', type: 'text' }
]}

// pseudocode — replicate the reserved list the sanitizer uses
const reservedBaseUploadFieldNames = ['filename','filesize','mimeType','url','width','height','focalX','focalY','thumbnailURL','sizes'] // verify against your Payload version
function checkUploadReservedNames(collection) {
  if (!collection.upload) return []
  const clashes = collection.fields
    .filter(f => f.name && reservedBaseUploadFieldNames.includes(f.name))
    .map(f => f.name)
  return clashes
}
// run for each upload collection before buildConfig()

function isReservedUploadName(name: string, reserved: string[]): boolean {
  return reserved.includes(name)
}

try {
  await payload.init({ config })
} catch (err) {
  if (err?.name === 'ReservedFieldName' || /reserved name/i.test(err?.message ?? '')) {
    console.error('Reserved upload field name:', err?.data?.fieldName)
  }
  throw err
}

When it happens

Trigger: Collection with `upload: true` (or `upload: {...}`) plus a field like `{ name: 'filename', type: 'text' }` or `{ name: 'mimeType', type: 'select' }`.

Common situations: 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.

Related errors

• Field "${field.name}" of type "${field.type}" has an empty r
• Field "${field.name}" is either missing a field type or it d
• Field ${field.label} has invalid name '${fieldName}'. Field
• Field ${field.label} has invalid relationship '${relationshi
• A field with the name '${fieldName}' was found multiple time

AI-assisted analysis of payloadcms/payload@00c58b35c0 (2026-08-12). Data as JSON: /api/errors/5c7ec5e4017226d8. Report an issue: GitHub.