payloadcms/payload · error · QueryError

The following path${results.length === 1 ? '' : 's'} cannot

Error message

The following path${results.length === 1 ? '' : 's'} cannot be queried: ${results.map((err) => err.path).join(', ')}

What it means

Thrown by `sanitizeJoinQuery` as a `QueryError` when a `joins` query parameter references join paths that are invalid. Payload validates each `joins[...]` path against the collection's configured `joins` and `polymorphicJoins`; unresolved or disallowed join paths accumulate into an `errors` array and are raised together. This is the join-query counterpart to `where`-path validation.

Source

Thrown at packages/payload/src/database/sanitizeJoinQuery.ts:152

  for (const join of collectionConfig.polymorphicJoins) {
    for (const collectionSlug of join.field.collection) {
      await sanitizeJoinFieldQuery({
        collectionSlug,
        errors,
        join,
        joinsQuery,
        overrideAccess,
        promises,
        req,
      })
    }
  }

  await Promise.all(promises)

  if (errors.length > 0) {
    throw new QueryError(errors)
  }

  return joinsQuery
}

View on GitHub (pinned to 00c58b35c0)

Solutions

Use only join field paths declared in the collection config.
Check the error's listed paths and remove unmatched ones.
After renaming a join field, update every consumer that builds `joins` params.

Example fix

// before
payload.find({ collection: 'posts', joins: { 'wrongName': { ... } } })
// after
payload.find({ collection: 'posts', joins: { 'comments': { ... } } })

Defensive patterns

Strategy: try-catch

Validate before calling

// Allowlist join field names before building the joins param
const joinFields = new Set(['comments', 'tags'])
function cleanJoins(joins: Record<string, any>) {
  return Object.fromEntries(Object.entries(joins).filter(([k]) => joinFields.has(k)))
}

Type guard

function isJoinField(name: string, cfg: { joins?: Record<string, unknown[]> }): boolean {
  return Boolean(cfg.joins && cfg.joins[name])
}

Try / catch

try {
  await payload.find({ collection, joins })
} catch (err) {
  if (err instanceof QueryError) {
    // remove the invalid join paths listed in err.data.errors, then retry
  }
  throw err
}

Prevention

Only pass join paths that exist in the collection config.
Update consumers after renaming a join field.
Validate joins params at the API boundary.

When it happens

Trigger: Passing `joins[invalidPath]=x` for a path that is not a configured join field; joining through a polymorphic join with a path the target collection rejects; typo in the join field name.

Common situations: Frontend building `joins` params dynamically from field names; misconfiguring a join field; querying after a join field rename.

Related errors

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