payloadcms/payload · error · Error

The hierarchy title field "${titleFieldName}" was not found.

Error message

The hierarchy title field "${titleFieldName}" was not found. It cannot be nested within named fields i.e. named groups, named tabs, etc.

What it means

Thrown by findUseAsTitleField.iterateFields when the field named by admin.useAsTitle cannot be located among the top-level or unnamed-group/unnamed-tab fields. The title lookup deliberately does not descend into named groups or named tabs, so a title field hidden inside one is not found.

Source

Thrown at packages/payload/src/hierarchy/utils/findUseAsTitle.ts:87

        break
      case 'tabs':
        for (const tab of field.tabs) {
          if (!('name' in tab)) {
            const result = iterateFields({ fields: tab.fields, titleFieldName })
            if (result) {
              titleField = result
            }
          }
        }
    }

    // If we found the field in recursion, return it
    if (titleField) {
      return titleField
    }
  }

  throw new Error(
    `The hierarchy title field "${titleFieldName}" was not found. It cannot be nested within named fields i.e. named groups, named tabs, etc.`,
  )
}

View on GitHub (pinned to 00c58b35c0)

Solutions

  1. Move the title field to the top level (or into an unnamed group/tab such as a row/collapsible).
  2. Point admin.useAsTitle at a top-level field instead.
  3. If the nested location is required, add a top-level alias field and populate it via a hook.
  4. Leave useAsTitle unset to fall back to 'id'.

Example fix

// before
fields: [
  { name: 'meta', type: 'group', fields: [
    { name: 'title', type: 'text' },
  ] },
],
admin: { useAsTitle: 'title' },
hierarchy: true,

// after
fields: [
  { name: 'title', type: 'text' },
],
admin: { useAsTitle: 'title' },
hierarchy: true,
Defensive patterns

Strategy: validation

Validate before calling

// helper: confirm useAsTitle is reachable at top level
import { iterateFields } from './findUseAsTitle'
try {
  iterateFields({ fields: collectionConfig.fields, titleFieldName })
} catch {
  throw new Error(`useAsTitle '${titleFieldName}' must be top-level / unnamed-group`)
}

Type guard

function titleFieldIsTopLevel(fields: Field[], name: string): boolean {
  return fields.some(
    (f) =>
      'name' in f && f.name === name &&
      ['text', 'number', 'textarea'].includes(f.type),
  )
}

Prevention

When it happens

Trigger: Setting admin.useAsTitle to a field that lives inside a named group or a named tab, on a collection with hierarchy enabled. Triggered when hierarchy code calls findUseAsTitleField during rendering/ancestry.

Common situations: Moving a title field into a named tab during a refactor; setting useAsTitle to a nested field expecting deep lookup; enabling hierarchy on a collection whose title is inside a named group.

Related errors

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