payloadcms/payload · error · Error

Hierarchy parent field "${parentFieldName}" in collection "$

Error message

Hierarchy parent field "${parentFieldName}" in collection "${collectionConfig.slug}" must have hasMany set to false

What it means

Thrown at sanitisation by sanitizeHierarchyCollection when the existing parent field is a relationship but hasMany is not explicitly false (i.e. hasMany:true or undefined treated as a hasMany violation per the strict check). Hierarchy supports a single parent only, so a multi-value relationship is rejected.

Source

Thrown at packages/payload/src/hierarchy/sanitizeHierarchyCollection.ts:62

  }

  const parentFieldName = collectionConfig.hierarchy.parentFieldName ?? defaultParentFieldName

  // Check if parent field already exists
  const existingParentField = collectionConfig.fields.find(
    (field) => fieldAffectsData(field) && field.name === parentFieldName,
  )

  if (existingParentField) {
    // Validate existing parent field configuration
    if (existingParentField.type !== 'relationship') {
      throw new Error(
        `Hierarchy parent field "${parentFieldName}" in collection "${collectionConfig.slug}" must be a relationship field`,
      )
    }

    if (existingParentField.hasMany !== false) {
      throw new Error(
        `Hierarchy parent field "${parentFieldName}" in collection "${collectionConfig.slug}" must have hasMany set to false`,
      )
    }

    if (existingParentField.localized === true) {
      throw new Error(
        `Hierarchy parent field "${parentFieldName}" in collection "${collectionConfig.slug}" cannot be localized. The parent relationship must be consistent across all locales.`,
      )
    }
  } else {
    // Auto-create parent field if it doesn't exist
    // useHeaderButton defaults to true - parent selection via header button with miller columns
    const useHeaderButton = collectionConfig.hierarchy.admin?.useHeaderButton ?? true

    const parentField = buildParentField({
      collectionSlug: collectionConfig.slug,
      injectHeaderButton: useHeaderButton,
      parentFieldName,

View on GitHub (pinned to 00c58b35c0)

Solutions

Set hasMany: false explicitly on the parent relationship field.
If you need a many-valued link, use a different field name and let hierarchy create its own single-valued parent.
Re-init Payload after the change.

Example fix

// before
{ name: 'parent', type: 'relationship', relationTo: 'pages', hasMany: true }

// after
{ name: 'parent', type: 'relationship', relationTo: 'pages', hasMany: false }

Defensive patterns

Strategy: validation

Validate before calling

const existing = collectionConfig.fields.find(
  (f) => fieldAffectsData(f) && f.name === parentFieldName,
)
if (existing && existing.hasMany !== false) {
  throw new Error(`Field ${parentFieldName} must have hasMany: false`)
}

Type guard

function isSingleRelationship(f: any): boolean {
  return f?.type === 'relationship' && f?.hasMany === false
}

Prevention

Always set hasMany:false explicitly on a reused parent field.
Avoid reusing a hasMany relationship as the hierarchy parent.

When it happens

Trigger: Declaring hierarchy on a collection whose existing parent relationship field has hasMany:true, or omitting hasMany:false so it does not satisfy the === false check.

Common situations: Reusing a prior many-to-many relationship field as the hierarchy parent; copying a field template that defaults hasMany to true.

Related errors

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