payloadcms/payload · error · Error

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

Error message

Hierarchy parent field "${parentFieldName}" in collection "${collectionConfig.slug}" cannot be localized. The parent relationship must be consistent across all locales.

What it means

Thrown at sanitisation by sanitizeHierarchyCollection when the existing parent relationship field has localized:true. Hierarchy requires the parent link to be identical across locales, so a localized parent field is rejected.

Source

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

    (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,
    })

    collectionConfig.fields.unshift(parentField)
  }

  // Apply defaults for optional fields

View on GitHub (pinned to 00c58b35c0)

Solutions

1. Set localized: false (or remove the localized flag) on the parent relationship field.
2. Use a non-localized field name for the parent and keep localized data on separate fields.
3. Re-init Payload after the change.

Example fix

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

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

const existing = collectionConfig.fields.find(
  (f) => fieldAffectsData(f) && f.name === parentFieldName,
)
if (existing && existing.localized === true) {
  throw new Error(`Field ${parentFieldName} cannot be localized`)
}

function isNonLocalizedRelationship(f: any): boolean {
  return f?.type === 'relationship' && f?.localized !== true
}

When it happens

Trigger: Declaring hierarchy on a collection whose existing parent relationship field is localized, typically because the field was reused from a localized content model.

Common situations: Reusing a localized relationship field as the hierarchy parent; enabling hierarchy on a collection that was previously localized-first.

Related errors

• Hierarchy parent field "${parentFieldName}" in collection "$
• Hierarchy parent field "${parentFieldName}" in collection "$
• The hierarchy title field "${titleFieldName}" was not found.
• Localization is not enabled in payload config
• ${collectionSlug ? 'Collection' : 'Global'} not found: ${col

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