payloadcms/payload · error · Error

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

Error message

Hierarchy parent field "${parentFieldName}" in collection "${collectionConfig.slug}" must be a relationship field

What it means

Thrown at config-sanitisation time by sanitizeHierarchyCollection when a collection declares hierarchy and an existing field with the resolved parentFieldName is present but is not of type 'relationship'. The parent link must be a relationship to the same collection, so a mismatched type blocks boot.

Source

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

  const defaultParentFieldName = getHierarchyFieldName(collectionConfig.slug)

  if (collectionConfig.hierarchy === true) {
    collectionConfig.hierarchy = {
      parentFieldName: defaultParentFieldName,
    }
  }

  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

View on GitHub (pinned to 00c58b35c0)

Solutions

Change the existing field's type to relationship (hasMany:false) pointing at the same collection.
Rename the conflicting field, or set hierarchy.parentFieldName to a fresh unused name so Payload auto-creates it.
Remove the conflicting field if it is unused.
After fixing, re-init Payload to re-run sanitisation.

Example fix

// before
export const Pages = { slug: 'pages', fields: [
  { name: 'parent', type: 'text' },
], hierarchy: true }

// after
export const Pages = { slug: 'pages', fields: [
  { name: 'parent', type: 'relationship', relationTo: 'pages', hasMany: false },
], hierarchy: true }

Defensive patterns

Strategy: validation

Validate before calling

// at config build time
const existing = collectionConfig.fields.find(
  (f) => fieldAffectsData(f) && f.name === parentFieldName,
)
if (existing && existing.type !== 'relationship') {
  throw new Error(`Field ${parentFieldName} must be a relationship`)
}

Type guard

import type { RelationshipField } from 'payload'
function isRelationship(f: any): f is RelationshipField {
  return f?.type === 'relationship'
}

Prevention

Run payload.init() in a smoke test as part of CI to catch config errors early.
Let hierarchy auto-create the parent field by using an unused parentFieldName.

When it happens

Trigger: Defining hierarchy: true on a collection that already has a field named the default parent field name (e.g. _parent) of type text/array/group, or naming hierarchy.parentFieldName after an existing non-relationship field.

Common situations: Enabling hierarchy on a collection that previously used that field name for another purpose; colliding with an auto-generated parent field name after a rename.

Related errors

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