payloadcms/payload · error · APIError

Unexpected array of collectionSlug, parent must be provided

Error message

Unexpected array of collectionSlug, parent must be provided

What it means

Thrown by buildTableState when `collectionSlug` is an array but `parent` is omitted. The array form is reserved for polymorphic join tables (a join whose target resolves to multiple collections); resolving the rows requires the parent document plus its `joinPath` so the table can be scoped to that single relationship. Without `parent`, the server has no way to select or join the correct documents.

Source

Thrown at packages/ui/src/utilities/buildTableState.ts:140

  const collectionPreferences = await upsertPreferences<CollectionPreferences>({
    key: preferencesKey,
    req,
    value: {
      columns: columnsFromArgs,
      limit: isNumber(query?.limit) ? Number(query.limit) : undefined,
      sort: query?.sort as string,
    },
  })

  let data: PaginatedDocs = dataFromArgs

  // lookup docs, if desired, i.e. within `join` field which initialize with `depth: 0`

  if (!data?.docs || query) {
    if (Array.isArray(collectionSlug)) {
      if (!parent) {
        throw new APIError('Unexpected array of collectionSlug, parent must be provided')
      }

      const select = {}
      let currentSelectRef = select

      const segments = parent.joinPath.split('.')

      for (let i = 0; i < segments.length; i++) {
        currentSelectRef[segments[i]] = i === segments.length - 1 ? true : {}
        currentSelectRef = currentSelectRef[segments[i]]
      }

      const joinQuery: { limit?: number; page?: number; sort?: string; where?: Where } = {
        sort: query?.sort as string,
        where: query?.where,
      }

      if (query) {

View on GitHub (pinned to 00c58b35c0)

Solutions

1. When passing an array of collection slugs, also pass a `parent` object containing `collectionSlug`, `id`, and `joinPath`.
2. If you are rendering a single collection's table, pass `collectionSlug` as a string, not an array.
3. Audit custom List/Table overrides to confirm they forward the `parent` prop for join tables.
4. Constrain the public caller's types so an array `collectionSlug` requires `parent`.

Example fix

// before
buildTableState({ collectionSlug: ['posts', 'pages'] })

// after
buildTableState({
  collectionSlug: ['posts', 'pages'],
  parent: { collectionSlug: 'users', id, joinPath: 'related' },
})

if (Array.isArray(collectionSlug) && !parent) {
  throw new Error(
    'parent (collectionSlug, id, joinPath) is required when collectionSlug is an array',
  )
}
// only then call buildTableState

function isValidJoinTableArgs(
  collectionSlug: unknown,
  parent: unknown,
): parent is { collectionSlug: string; id: number | string; joinPath: string } {
  if (!Array.isArray(collectionSlug)) return true // single slug needs no parent
  return (
    !!parent &&
    typeof parent === 'object' &&
    typeof (parent as any).collectionSlug === 'string' &&
    (parent as any).id !== undefined &&
    typeof (parent as any).joinPath === 'string'
  )
}

When it happens

Trigger: Invoking the table-state server function with an array `collectionSlug` and no `parent.collectionSlug`/`parent.id`/`parent.joinPath`; a custom client component forwarding multiple collection slugs for what is actually a single-collection table; a regression in join rendering that drops the `parent` prop.

Common situations: Custom relationship/join UIs that reuse buildTableState incorrectly, refactors of join field rendering that stop forwarding `parent`, client code sending an array where the server expects a single slug.

Related errors

• Invalid template given
• Invalid database type given. Valid types are: ${Object.value
• No version or tag "${version}" found for package: ${packageN
• Either collection or globalSlug must be passed.
• Either collectionSlug or globalSlug must be provided

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