payloadcms/payload · error · DuplicateFieldName

A field with the name '${fieldName}' was found multiple time

Error message

A field with the name '${fieldName}' was found multiple times on the same level. Field names must be unique.

What it means

Two data-affecting fields at the same nesting level share the same `name`. Payload tracks field names per level in an `existingFieldNames` set; a duplicate would map to the same DB column and admin form key, so it is rejected. (`blockName` and `id` are exempt because they are system-managed.)

Source

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

    ]
  }

  // Array ID field
  if (field.type === 'array' && field.fields) {
    const hasCustomID = field.fields.some((f) => 'name' in f && f.name === 'id')
    if (!hasCustomID) {
      field.fields.push(baseIDField)
    }
  }

  // Blocks/array labels
  if ((field.type === 'blocks' || field.type === 'array') && field.label) {
    field.labels = field.labels || formatLabels(field.name)
  }

  if (fieldAffectsData) {
    if (existingFieldNames.has(field.name)) {
      throw new DuplicateFieldName(field.name)
    } else if (!['blockName', 'id'].includes(field.name)) {
      existingFieldNames.add(field.name)
    }

    if (typeof field.localized !== 'undefined') {
      if (!config.localization) {
        delete field.localized
      }
    }

    if (typeof field.validate === 'undefined') {
      if ('virtual' in field && field.virtual) {
        field.validate = (): true => true
      } else {
        const defaultValidate = validations[field.type as keyof typeof validations]
        if (defaultValidate) {
          field.validate = (val: any, options: any) =>
            defaultValidate(val, { ...field, ...options })

View on GitHub (pinned to 00c58b35c0)

Solutions

Rename one of the duplicate fields to a unique name within that level.
If the duplication is intentional, separate the fields into different groups or named tabs (each named tab/group has its own name scope).
Search the offending level's fields for the reported name to find both occurrences.

Example fix

// before
fields: [
  { name: 'title', type: 'text' },
  { name: 'title', type: 'textarea' }
]
// after
fields: [
  { name: 'title', type: 'text' },
  { name: 'subtitle', type: 'textarea' }
]

Defensive patterns

Strategy: validation

Validate before calling

function findDuplicateFieldNames(fields) {
  const seen = new Set(); const dupes = []
  for (const f of fields) {
    if (!f?.name || ['blockName','id'].includes(f.name)) continue
    if (seen.has(f.name)) dupes.push(f.name); else seen.add(f.name)
  }
  return dupes
}
// run per collection/global and per group/tab/array scope

Type guard

function fieldsAreUniqueByName(fields: any[]): boolean {
  const names = fields.filter(f => f?.name && !['blockName','id'].includes(f.name)).map(f => f.name)
  return new Set(names).size === names.length
}

Try / catch

try {
  await payload.init({ config })
} catch (err) {
  if (err?.name === 'DuplicateFieldName') console.error('Duplicate field name:', err?.message)
  throw err
}

Prevention

When merging field arrays from multiple modules, dedupe by name first.
Add a unit test that asserts each collection's top-level field names are unique.

When it happens

Trigger: Two `{ name: 'title', type: 'text' }` in one collection's fields; a group containing two children with the same name; a tab and a sibling field sharing a name.

Common situations: Copy-pasting a field and forgetting to rename; merging two configs; refactoring tabs/groups and accidentally producing two same-named fields at the same level.

Related errors

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