What causes "Missing 'where' query of documents to update." in payloadcms/payload?

Provide an explicit `where` clause to scope the update.

payloadcms/payload · error · APIError

Missing 'where' query of documents to update.

Error message

Missing 'where' query of documents to update.

What it means

Thrown at packages/payload/src/collections/operations/update.ts:122 with HTTP 400 (BAD_REQUEST) inside `updateOperation` when the `where` argument is falsy. Because this is the bulk-update path, Payload requires a `where` clause to scope which documents change; omitting it would otherwise update every document. The guard runs after beforeOperation hooks and the disableBulkEdit check, before access control.

Source

Thrown at packages/payload/src/collections/operations/update.ts:122

      populate,
      publishAllLocales,
      req: {
        fallbackLocale,
        locale,
        payload: { config },
        payload,
      },
      req,
      select: incomingSelect,
      showHiddenFields,
      sort: incomingSort,
      trash = false,
      unpublishAllLocales,
      where,
    } = args

    if (!where) {
      throw new APIError("Missing 'where' query of documents to update.", httpStatus.BAD_REQUEST)
    }

    const { data: bulkUpdateData } = args
    const shouldSaveDraft = Boolean(draftArg && hasDraftsEnabled(collectionConfig))

    // /////////////////////////////////////
    // Access
    // /////////////////////////////////////

    let accessResult: AccessResult
    if (!overrideAccess) {
      accessResult = await executeAccess(
        { slug: collectionConfig.slug, req },
        collectionConfig.access.update,
      )
    }

    await validateQueryPaths({

View on GitHub (pinned to 00c58b35c0)

Solutions

Provide an explicit `where` clause to scope the update.
If you truly mean 'update a single document', use the id-based form: `payload.update({ collection, id, data })`.
Validate at the API boundary that `where` is present before forwarding to the bulk Local API.

Example fix

// before — bulk update without a where clause
await payload.update({ collection: 'posts', data: { status: 'published' } })

// after — scope the update explicitly
await payload.update({ collection: 'posts', where: { status: { equals: 'draft' } }, data: { status: 'published' } })
// or update a single document by id
await payload.update({ collection: 'posts', id, data: { status: 'published' } })

Defensive patterns

Strategy: validation

Validate before calling

function assertWhereClause(where: unknown): asserts where is NonNullable<Where> {
  if (!where || (typeof where === 'object' && Object.keys(where).length === 0)) {
    throw new Error('A non-empty where clause is required for bulk update.')
  }
}

assertWhereClause(where)
await payload.update({ collection: 'posts', where, data })
// if you only mean to update one doc, use: payload.update({ collection: 'posts', id, data })

Type guard

import type { Where } from 'payload'

const hasWhereClause = (where: unknown): where is Where =>
  typeof where === 'object' && where !== null && Object.keys(where).length > 0

if (hasWhereClause(where)) {
  await payload.update({ collection: 'posts', where, data })
} else if (id) {
  await payload.update({ collection: 'posts', id, data })
} else {
  // reject: neither a where clause nor an id was provided
}

Try / catch

try {
  await payload.update({ collection: 'posts', where, data })
} catch (err) {
  if (err instanceof APIError && err.status === 400 && /Missing 'where' query/.test(err.message)) {
    // caller forgot the where clause — require it, or switch to single-doc update
  } else throw err
}

Prevention

Validate at the API boundary that bulk-update requests include a non-empty where clause.
Use the single-doc update form ({ collection, id, data }) when targeting one document.
Never default an absent where clause to {} (empty), since bulk update without a filter is almost never intended.

When it happens

Trigger: Calling `payload.update({ collection, data })` in the many-doc form without a `where` field; destructuring `where` from a request body where the client omitted it; a refactor that dropped the where clause assuming an empty filter means 'all'.

Common situations: Confusing the single-doc update signature (`{ collection, id, data }`) with the bulk signature (`{ collection, where, data }`); client sends a PUT/PATCH body without a filter; migration script that forgot the where clause.

Related errors

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