payloadcms/payload · error · APIError

Failed to retrieve array of joins for ${slug} in collectio $

Error message

Failed to retrieve array of joins for ${slug} in collectio ${collection}

What it means

Thrown while iterating `Object.keys(joinConfig)` when `joinConfig[slug]` is nullish. NOTE the message has a typo ('collectio') and interpolates `collection`. Normally near-unreachable because keys come from the object itself, but possible if a sanitized join config contains an explicit `null`/`undefined` value under a key.

Source

Thrown at packages/db-mongodb/src/utilities/buildJoinAggregation.ts:263

          $gt: [{ $size: `$${as}.docs` }, limitJoin || Number.MAX_VALUE],
        },
      },
    })

    aggregate.push({
      $set: {
        [`${as}.docs`]: {
          $slice: [`$${as}.docs`, ...sliceValue],
        },
      },
    })
  }

  for (const slug of Object.keys(joinConfig)) {
    const joinsList = joinConfig[slug]

    if (!joinsList) {
      throw new APIError(`Failed to retrieve array of joins for ${slug} in collectio ${collection}`)
    }

    for (const join of joinsList) {
      const projectionPath = versions ? `version.${join.joinPath}` : join.joinPath
      if (projection && !projection[projectionPath]) {
        continue
      }

      if (joins?.[join.joinPath] === false) {
        continue
      }

      const collectionConfig = adapter.payload.collections[join.field.collection as string]?.config

      if (!collectionConfig) {
        throw new APIError(
          `Collection config for ${join.field.collection.toString()} was not found`,
        )

View on GitHub (pinned to 00c58b35c0)

Solutions

1. Inspect the collection's sanitized `joins` object for null/undefined values.
2. Re-run sanitization by restarting the process so config is rebuilt cleanly.
3. Verify each join field definition is complete and valid.
4. If reproducing, report with the sanitized config dump — this path is normally defensive.

Example fix

// malformed sanitized config
{ joins: { author: null } }
// fix: ensure join is fully defined or removed
{ joins: { author: [{ field: {...}, ... }] } }

function assertJoinsList(joinConfig, slug, collection) {
  const list = joinConfig[slug]
  if (!list) throw new Error(`Null join list for ${slug} in ${collection}`)
  return list
}

const isValidJoinsEntry = (joinConfig, slug) =>
  Boolean(joinConfig && joinConfig[slug])

try { await payload.find({ collection, joins }) }
catch (e) { if (/Failed to retrieve array of joins/.test(e.message)) dumpSanitizedJoins(collection) else throw e }

When it happens

Trigger: A sanitized join config shaped like `{ somePath: null }` — a key exists but its value is nullish, so the inner `for (const join of joinsList)` would fail.

Common situations: Hand-edited or programmatically-malformed sanitized config; a partial migration that left null entries; a bug in join sanitization producing null values for a path.

Related errors

• Could not retrieve sanitized join config for ${collection}.
• Could not retrieve sanitized polymorphic joins config for ${
• Collection config for ${join.field.collection.toString()} wa
• Global with the slug ${globalSlug} was not found
• Collection with the slug ${globalSlug} was not found

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