payloadcms/payload · error · APIError

The folder "${data.name || originalDoc.name}" contains ${isF

Error message

The folder "${data.name || originalDoc.name}" contains ${isFolder ? 'folders' : 'documents'} that still belong to the following collections: ${translatedLabels.join(', ')}

What it means

Thrown by the ensureSafeCollectionsChange beforeValidate hook when a folder is having its allowed collection types narrowed (or its type set in a way that removes collections), but documents or child folders still reference the folder through those collections. HTTP 400 APIError.

Source

Thrown at packages/payload/src/hierarchy/hooks/ensureSafeCollectionsChange.ts:99

            if (childFoldersResult.totalDocs > 0) {
              dependentCollection = foldersSlug
            }
          }
        }

        if (dependentCollection) {
          const translatedLabels = newCollections.map((collectionSlug) => {
            if (req.payload.collections[collectionSlug]?.config.labels.singular) {
              return getTranslatedLabel(
                req.payload.collections[collectionSlug]?.config.labels.plural,
                req.i18n,
              )
            }
            return collectionSlug
          })

          const isFolder = dependentCollection === foldersSlug
          throw new APIError(
            `The folder "${data.name || originalDoc.name}" contains ${isFolder ? 'folders' : 'documents'} that still belong to the following collections: ${translatedLabels.join(', ')}`,
            400,
          )
        }

        return data
      }
    } else if (
      (data?.[typeFieldName] === null ||
        (Array.isArray(data?.[typeFieldName]) && data?.[typeFieldName].length === 0)) &&
      newParentDocID
    ) {
      // attempting to set the type to catch-all, so we need to ensure that the parent allows this
      let parentFolder
      if (typeof newParentDocID === 'string' || typeof newParentDocID === 'number') {
        try {
          parentFolder = await req.payload.findByID({
            id: newParentDocID,

View on GitHub (pinned to 00c58b35c0)

Solutions

1. Move or delete the dependent documents/folders first, then narrow the folder's type list.
2. If the removal is intentional, reassign the affected documents to another folder in a prior step.
3. Surface the error's collection list to the user so they know what to clean up.
4. Disable the type-narrowing control when the folder is non-empty.

Example fix

// before
await payload.update({ collection: 'payload-folders', id: folderId, data: { hierarchyType: ['pages'] } })

// after — reassign dependents first
await payload.update({
  collection: 'posts',
  where: { folder: { equals: folderId } },
  data: { folder: newFolderId },
})
await payload.update({ collection: 'payload-folders', id: folderId, data: { hierarchyType: ['pages'] } })

for (const removed of removedCollections) {
  const { totalDocs } = await payload.find({
    collection: removed,
    where: { [folderFieldName]: { equals: folderId } },
    limit: 1,
    overrideAccess: true,
  })
  if (totalDocs > 0) throw new Error(`${removed} still has docs here`)
}

function folderIsEmpty(counts: Record<string, number>): boolean {
  return Object.values(counts).every((c) => c === 0)
}

try {
  await payload.update({ collection: foldersSlug, id: folderId, data })
} catch (err) {
  if (err instanceof APIError && err.statusCode === 400 && /still belong/.test(err.message)) {
    return { error: err.message }
  }
  throw err
}

When it happens

Trigger: Updating a folder's hierarchyType array to remove 'posts' while documents whose folder field points at this folder still have collection 'posts'; likewise removing a type that a child folder still declares.

Common situations: Reorganising folder taxonomy without first moving or deleting the documents that depend on it; UI letting users narrow folder types while content is still attached.

Related errors

• The folder "${data?.name || originalDoc.name}" must have fol
• Collection ${collectionSlug} is not a hierarchy
• Document cannot be its own parent
• Circular reference detected: the parent chain contains a loo
• Cannot move folder into its own subfolder

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