payloadcms/payload · error · APIError

Could not retrieve sanitized polymorphic joins config for ${

Error message

Could not retrieve sanitized polymorphic joins config for ${collection}.

What it means

Companion to the join-config error: thrown when `adapter.payload.collections[collection]?.config?.polymorphicJoins` is falsy even though the raw config indicated polymorphic joins exist. Indicates incomplete sanitization or a slug mismatch for the target collection.

Source

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

  if (
    (Object.keys(collectionConfig.joins).length === 0 &&
      collectionConfig.polymorphicJoins.length == 0) ||
    joins === false
  ) {
    return []
  }

  const joinConfig = adapter.payload.collections[collection]?.config?.joins

  if (!joinConfig) {
    throw new APIError(`Could not retrieve sanitized join config for ${collection}.`)
  }

  const aggregate: PipelineStage[] = []
  const polymorphicJoinsConfig = adapter.payload.collections[collection]?.config?.polymorphicJoins

  if (!polymorphicJoinsConfig) {
    throw new APIError(`Could not retrieve sanitized polymorphic joins config for ${collection}.`)
  }

  for (const join of polymorphicJoinsConfig) {
    if (projection && !projection[join.joinPath]) {
      continue
    }

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

    const {
      count = false,
      limit: limitJoin = join.field.defaultLimit ?? 10,
      page,
      sort: sortJoin = join.field.defaultSort || collectionConfig.defaultSort,
      where: whereJoin = {},
    } = joins?.[join.joinPath] || {}

View on GitHub (pinned to 00c58b35c0)

Solutions

1. Verify the target collection slug is registered and sanitized.
2. Confirm all collections referenced by polymorphic joins are loaded.
3. Await init; restart to rebuild sanitized configs.
4. Check plugin load order if joins cross plugin boundaries.

Example fix

// before
polymorphic join references 'media' but plugin not registered
// after
payload.init({ collections: [...coreCollections, ...mediaPluginCollections] })

function assertPolymorphicJoins(payload, collection) {
  const cfg = payload.collections[collection]?.config?.polymorphicJoins
  if (!cfg) throw new Error(`No sanitized polymorphic joins for ${collection}`)
  return cfg
}

const hasSanitizedPolymorphicJoins = (payload, c) =>
  Boolean(payload.collections[c]?.config?.polymorphicJoins)

try { await payload.find({ collection, joins: {...} }) }
catch (e) { if (/sanitized polymorphic joins/.test(e.message)) handleBadPolyJoin(c) else throw e }

When it happens

Trigger: A query that triggers polymorphic join aggregation where the target collection's sanitized config lacks `polymorphicJoins` — slug mismatch, sanitization dropped the entry, or query during init.

Common situations: Renamed collection; polymorphic join target collection not loaded (e.g. plugin providing it not registered); sanitization failure on the join target; init race.

Related errors

• Could not retrieve sanitized join config for ${collection}.
• Failed to retrieve array of joins for ${slug} in collectio $
• 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/6231f175649ab76b. Report an issue: GitHub.