What causes "Not supported" in payloadcms/payload?

Restructure the join to target a single collection if you need nested filtering (`collection: 'posts'`).

payloadcms/payload · error · APIError

Not supported

Error message

Not supported

What it means

Thrown by `getLocalizedPaths` when a query drills into a nested path through a polymorphic join field — one whose `collection` is an array (it joins to multiple target collections). Payload only supports nested querying through single-collection relationships/joins; a multi-target join has no single schema to resolve nested fields against, so it is rejected with HTTP 500 'Not supported'.

Source

Thrown at packages/payload/src/database/getLocalizedPaths.ts:182

              lastIncompletePath.path = pathSegments.join('.')
              if (![matchedField.name, 'relationTo', 'value'].includes(pathSegments.at(-1)!)) {
                lastIncompletePath.invalid = true
              } else {
                lastIncompletePath.complete = true
              }
            } else {
              lastIncompletePath.complete = true
              lastIncompletePath.path = currentPath!

              const nestedPathToQuery = pathSegments
                .slice(nextSegmentIsLocale ? i + 2 : i + 1)
                .join('.')

              if (nestedPathToQuery) {
                let relatedCollection: SanitizedCollectionConfig
                if (matchedField.type === 'join') {
                  if (Array.isArray(matchedField.collection)) {
                    throw new APIError('Not supported')
                  }

                  relatedCollection = payload.collections[matchedField.collection]!.config
                } else {
                  relatedCollection = payload.collections[matchedField.relationTo as string]!.config
                }

                const remainingPaths = getLocalizedPaths({
                  collectionSlug: relatedCollection.slug,
                  fields: relatedCollection.flattenedFields,
                  globalSlug,
                  incomingPath: nestedPathToQuery,
                  locale,
                  parentIsLocalized: false,
                  payload,
                })

                paths = [...paths, ...remainingPaths]

View on GitHub (pinned to 00c58b35c0)

Solutions

Restructure the join to target a single collection if you need nested filtering (`collection: 'posts'`).
Filter on the join field directly (e.g. `where[myJoinField.id]`) without descending into target-collection fields.
Run separate queries per target collection instead of one polymorphic nested query.

Example fix

// before: polymorphic join, nested query fails
{ name: 'related', type: 'join', collection: ['posts', 'pages'] }
// query: where[related.title]=x  -> throws
// after: single-collection join
{ name: 'related', type: 'join', collection: 'posts' }
// query: where[related.title]=x  -> ok

Defensive patterns

Strategy: validation

Validate before calling

// Detect polymorphic joins and avoid nested where paths on them
for (const f of collectionConfig.fields) {
  if (f.type === 'join' && Array.isArray(f.collection)) {
    console.warn(`Join '${f.name}' is polymorphic; do not query nested paths through it.`)
  }
}

Type guard

function isPolymorphicJoin(f: any): boolean {
  return f?.type === 'join' && Array.isArray(f?.collection)
}

Try / catch

try {
  await payload.find({ collection, where: { 'related.title': { equals: 'x' } } })
} catch (err) {
  if (err instanceof APIError && /Not supported/.test(err.message)) {
    // switch to single-collection join or query targets separately
  }
  throw err
}

Prevention

Use single-collection joins when you need nested filtering.
Filter only on the join field's own id/relationTo for polymorphic joins.
Document polymorphic-join limitations for API consumers.

When it happens

Trigger: Querying `where[myJoinField.title][equals]=x` where `myJoinField` is a join field with `collection: ['posts', 'pages']` (polymorphic); using a deep `where` path on a join that targets more than one collection.

Common situations: A 'related items' join field configured across multiple collections; clients building dynamic filters that walk into joined relations; migrating from a single-collection join to multi-collection without updating queries.

Related errors

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