payloadcms/payload · warning · APIError

field must be specified

Error message

field must be specified

What it means

The `findDistinctHandler` REST handler parses query params; if `field` is absent/empty it throws an `APIError` (400). The distinct endpoint must know which field to deduplicate values on, so a missing `field` is a malformed request.

Source

Thrown at packages/payload/src/collections/endpoints/findDistinct.ts:17

import { status as httpStatus } from 'http-status'

import type { PayloadHandler } from '../../config/types.js'

import { APIError } from '../../errors/APIError.js'
import { getRequestCollection } from '../../utilities/getRequestEntity.js'
import { headersWithCors } from '../../utilities/headersWithCors.js'
import { parseParams } from '../../utilities/parseParams/index.js'
import { findDistinctOperation } from '../operations/findDistinct.js'

export const findDistinctHandler: PayloadHandler = async (req) => {
  const collection = getRequestCollection(req)

  const { depth, field, limit, page, sort, trash, where } = parseParams(req.query)

  if (!field) {
    throw new APIError('field must be specified', httpStatus.BAD_REQUEST)
  }

  const result = await findDistinctOperation({
    collection,
    depth,
    field,
    limit,
    page,
    req,
    sort,
    trash,
    where,
  })

  return Response.json(result, {
    headers: headersWithCors({
      headers: new Headers(),
      req,

View on GitHub (pinned to 00c58b35c0)

Solutions

1. Add `?field=<fieldName>` to the request.
2. Validate the param in the client before issuing the request.

Example fix

// before
fetch('/api/posts/distinct')
// after
fetch(`/api/posts/distinct?field=${encodeURIComponent('category')}`)

function buildDistinctUrl(collection, field) {
  if (!field) throw new Error('field query param is required')
  return `/api/${collection}/distinct?field=${encodeURIComponent(field)}`
}

function hasFieldParam(query): query is { field: string } {
  return typeof query?.field === 'string' && query.field.length > 0
}

When it happens

Trigger: `GET /api/{collection}/distinct` without a `field` query param, or with `field=` (empty string). The parsed `field` is falsy.

Common situations: Client forgetting the `field` param; URL builder dropping it; typo such as `?fields=` (plural).

Related errors

• Field ${args.field} was not found in the collection ${collec
• The following fields are invalid: ${fieldPaths}
• A valid URL string is required.
• Upload collection ${upload.collectionSlug} was not found
• Invalid template given

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