payloadcms/payload · error · Error

Collection ${collectionSlug} is not a hierarchy

Error message

Collection ${collectionSlug} is not a hierarchy

What it means

Thrown by getInitialTreeData when payload.collections[collectionSlug] either does not exist or its config has no hierarchy block. It guards the tree-data loader before touching the parent field. A plain Error (HTTP 500 via the generic handler).

Source

Thrown at packages/payload/src/hierarchy/getInitialTreeData.ts:42

  // Metadata about what was loaded - keyed by parent ID ('null' for root)
  loadedParents: Record<string, { hasMore: boolean; loadedCount?: number; totalDocs: number }>
}

export const getInitialTreeData = async ({
  baseFilter,
  collectionSlug,
  expandedNodeIds = [],
  filterByCollections,
  limit,
  payload,
  selectedNodeId,
  selectedNodeParentId,
  user,
}: GetInitialTreeDataArgs): Promise<InitialTreeData> => {
  const collectionConfig = payload.collections[collectionSlug]?.config

  if (!collectionConfig || !collectionConfig.hierarchy) {
    throw new Error(`Collection ${collectionSlug} is not a hierarchy`)
  }

  const hierarchyConfig = collectionConfig.hierarchy
  const parentFieldName = hierarchyConfig.parentFieldName
  const useAsTitle = collectionConfig.admin?.useAsTitle ?? 'id'

  // Get typeFieldName for filtering
  const typeFieldName =
    hierarchyConfig.collectionSpecific && typeof hierarchyConfig.collectionSpecific === 'object'
      ? hierarchyConfig.collectionSpecific.fieldName
      : undefined

  // Build filter condition if filterByCollections is provided
  // Exclude the hierarchy collection itself (folders always show folders)
  const filteredTypes = filterByCollections?.filter((t) => t !== collectionSlug)

  // Get all possible type values from relatedCollections for detecting empty arrays
  const allPossibleTypes = hierarchyConfig.relatedCollections

View on GitHub (pinned to 00c58b35c0)

Solutions

1. Enable hierarchy on the collection: set hierarchy: true (or an object) in the collection config and re-init Payload.
2. Pass a collectionSlug that you have verified has collectionConfig.hierarchy truthy.
3. Type-narrow the slug against a list of known hierarchy collections before calling.
4. If the collection was recently enabled, restart the server so the sanitized config is in effect.

Example fix

// before
const tree = await getInitialTreeData({ collectionSlug: 'pages', payload, user })

// after
const cfg = payload.collections['pages']?.config
if (!cfg?.hierarchy) {
  throw new Error('Enable hierarchy on the pages collection first')
}
const tree = await getInitialTreeData({ collectionSlug: 'pages', payload, user })

const cfg = payload.collections[collectionSlug]?.config
if (!cfg?.hierarchy) {
  throw new Error(`${collectionSlug} is not a hierarchy collection`)
}

function isHierarchyCollection(
  payload: Payload,
  slug: string,
): boolean {
  return Boolean(payload.collections[slug]?.config?.hierarchy)
}

try {
  return await getInitialTreeData({ collectionSlug, payload, user })
} catch (err) {
  if (err instanceof Error && /not a hierarchy/.test(err.message)) return { docs: [], loadedParents: {} }
  throw err
}

When it happens

Trigger: Calling getInitialTreeData({ collectionSlug: 'pages', ... }) where 'pages' is a normal collection without hierarchy: true, or where the slug is mistyped.

Common situations: Pointing a folder/tree UI at a collection that was never configured for hierarchy; enabling hierarchy on a different collection than the UI expects; slug typo.

Related errors

• Collection "${collectionSlug}" not found
• The hierarchy title field "${titleFieldName}" was not found.
• Collection "${hierarchySlug}" is not a hierarchy
• Collection is not a hierarchy
• Invalid template given

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