{"record":{"id":"671f6885bc307fd1","repo":"payloadcms/payload","slug":"hierarchy-parent-field-parentfieldname-in-col-671f68","errorCode":null,"errorMessage":"Hierarchy parent field \"${parentFieldName}\" in collection \"${collectionConfig.slug}\" cannot be localized. The parent relationship must be consistent across all locales.","messagePattern":"Hierarchy parent field \"(.+?)\" in collection \"(.+?)\" cannot be localized\\. The parent relationship must be consistent across all locales\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/payload/src/hierarchy/sanitizeHierarchyCollection.ts","lineNumber":68,"sourceCode":"    (field) => fieldAffectsData(field) && field.name === parentFieldName,\n  )\n\n  if (existingParentField) {\n    // Validate existing parent field configuration\n    if (existingParentField.type !== 'relationship') {\n      throw new Error(\n        `Hierarchy parent field \"${parentFieldName}\" in collection \"${collectionConfig.slug}\" must be a relationship field`,\n      )\n    }\n\n    if (existingParentField.hasMany !== false) {\n      throw new Error(\n        `Hierarchy parent field \"${parentFieldName}\" in collection \"${collectionConfig.slug}\" must have hasMany set to false`,\n      )\n    }\n\n    if (existingParentField.localized === true) {\n      throw new Error(\n        `Hierarchy parent field \"${parentFieldName}\" in collection \"${collectionConfig.slug}\" cannot be localized. The parent relationship must be consistent across all locales.`,\n      )\n    }\n  } else {\n    // Auto-create parent field if it doesn't exist\n    // useHeaderButton defaults to true - parent selection via header button with miller columns\n    const useHeaderButton = collectionConfig.hierarchy.admin?.useHeaderButton ?? true\n\n    const parentField = buildParentField({\n      collectionSlug: collectionConfig.slug,\n      injectHeaderButton: useHeaderButton,\n      parentFieldName,\n    })\n\n    collectionConfig.fields.unshift(parentField)\n  }\n\n  // Apply defaults for optional fields","sourceCodeStart":50,"sourceCodeEnd":86,"githubUrl":"https://github.com/payloadcms/payload/blob/00c58b35c0ed348ddc22daabf467b139727214fd/packages/payload/src/hierarchy/sanitizeHierarchyCollection.ts#L50-L86","documentation":"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.","triggerScenarios":"Declaring hierarchy on a collection whose existing parent relationship field is localized, typically because the field was reused from a localized content model.","commonSituations":"Reusing a localized relationship field as the hierarchy parent; enabling hierarchy on a collection that was previously localized-first.","solutions":["Set localized: false (or remove the localized flag) on the parent relationship field.","Use a non-localized field name for the parent and keep localized data on separate fields.","Re-init Payload after the change."],"exampleFix":"// before\n{ name: 'parent', type: 'relationship', relationTo: 'pages', hasMany: false, localized: true }\n\n// after\n{ name: 'parent', type: 'relationship', relationTo: 'pages', hasMany: false, localized: false }","handlingStrategy":"validation","validationCode":"const existing = collectionConfig.fields.find(\n  (f) => fieldAffectsData(f) && f.name === parentFieldName,\n)\nif (existing && existing.localized === true) {\n  throw new Error(`Field ${parentFieldName} cannot be localized`)\n}","typeGuard":"function isNonLocalizedRelationship(f: any): boolean {\n  return f?.type === 'relationship' && f?.localized !== true\n}","tryCatchPattern":null,"preventionTips":["Keep the parent field non-localized; store localized content on separate fields.","Do not reuse a localized relationship as the hierarchy parent."],"tags":["hierarchy","config","sanitization","fields","localization"],"backgroundTag":null,"analyzedSha":"00c58b35c0ed348ddc22daabf467b139727214fd","analyzedAt":"2026-08-12T20:45:03.758Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}