payloadcms/payload · error · APIError

The folder "${data?.name || originalDoc.name}" must have fol

Error message

The folder "${data?.name || originalDoc.name}" must have folder-type set since its parent folder ${parentFolder?.name ? `"${parentFolder?.name}" ` : ''}has a folder-type set.

What it means

Thrown by ensureSafeCollectionsChange when a folder's hierarchyType is being cleared (set to null/empty) while its parent folder still has a restricted type list. A child cannot be a catch-all when its parent is typed. HTTP 400 APIError.

Source

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

            select: {
              name: true,
              [typeFieldName]: true,
            },
            user: req.user,
          })
        } catch (_) {
          // parent folder does not exist
        }
      }

      const parentTypeValue = parentFolder?.[typeFieldName]
      if (
        parentFolder &&
        parentTypeValue &&
        Array.isArray(parentTypeValue) &&
        parentTypeValue.length > 0
      ) {
        throw new APIError(
          `The folder "${data?.name || originalDoc.name}" must have folder-type set since its parent folder ${parentFolder?.name ? `"${parentFolder?.name}" ` : ''}has a folder-type set.`,
          400,
        )
      }
    }

    return data
  }

View on GitHub (pinned to 00c58b35c0)

Solutions

1. Keep a non-empty hierarchyType that is a subset of the parent's allowed types.
2. Clear or widen the parent's type first, then clear the child's.
3. Move the folder to an untyped parent before clearing its type.
4. In the UI, disable clearing the type when the parent is typed.

Example fix

// before
await payload.update({ collection: 'payload-folders', id: childId, data: { hierarchyType: null } })

// after — inherit a valid subset of the parent's types
const parent = await payload.findByID({ collection: 'payload-folders', id: parentId })
await payload.update({
  collection: 'payload-folders',
  id: childId,
  data: { hierarchyType: parent.hierarchyType },
})

const parent = await payload.findByID({
  collection: foldersSlug,
  id: parentId,
  overrideAccess: true,
})
if (Array.isArray(parent?.[typeFieldName]) && parent[typeFieldName].length > 0) {
  throw new Error('parent is typed; child must keep a type')
}

function parentIsTyped(parent: any, typeFieldName: string): boolean {
  return Array.isArray(parent?.[typeFieldName]) && parent[typeFieldName].length > 0
}

try {
  await payload.update({ collection: foldersSlug, id: childId, data })
} catch (err) {
  if (err instanceof APIError && err.statusCode === 400 && /folder-type set/.test(err.message)) {
    return { error: err.message }
  }
  throw err
}

When it happens

Trigger: Setting data.hierarchyType to null or [] on a folder whose parent (resolved via data.folder/originalDoc.folder) has a non-empty hierarchyType array.

Common situations: User clears the folder-type field without realising the parent constrains it; moving an untyped folder under a typed parent via the UI.

Related errors

• The folder "${data.name || originalDoc.name}" contains ${isF
• 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/019b2d64ef9b22f5. Report an issue: GitHub.