payloadcms/payload · warning · APIError

Field ${args.field} was not found in the collection ${collec

Error message

Field ${args.field} was not found in the collection ${collectionConfig.slug}

What it means

In `findDistinctOperation`, `getFieldByPath` resolves the requested `field` against the collection's flattened fields; if it returns null, the field does not exist (or its path doesn't resolve), so an `APIError` (400) is thrown.

Source

Thrown at packages/payload/src/collections/operations/findDistinct.ts:127

      where: fullWhere,
    })

    await validateQueryPaths({
      collectionConfig,
      overrideAccess: overrideAccess!,
      req,
      where: where ?? {},
    })

    const fieldResult = getFieldByPath({
      config: payload.config,
      fields: collectionConfig.flattenedFields,
      includeRelationships: true,
      path: args.field,
    })

    if (!fieldResult) {
      throw new APIError(
        `Field ${args.field} was not found in the collection ${collectionConfig.slug}`,
        httpStatus.BAD_REQUEST,
      )
    }

    if (fieldResult.field.hidden && !showHiddenFields) {
      throw new Forbidden(req.t)
    }

    if (fieldResult.field.access?.read) {
      const hasAccess = await fieldResult.field.access.read({
        collection: collectionConfig,
        req,
      })
      if (!hasAccess) {
        throw new Forbidden(req.t)
      }
    }

View on GitHub (pinned to 00c58b35c0)

Solutions

Use a field name that exists on the collection.
For nested/relationship fields, use the correct dotted path that `getFieldByPath` can resolve.

Example fix

// before
await payload.findDistinct({ collection: 'posts', field: 'cat' })
// after
await payload.findDistinct({ collection: 'posts', field: 'category' })

Defensive patterns

Strategy: validation

Validate before calling

function fieldExists(collectionConfig, field) {
  return collectionConfig.flattenedFields.some(f => f.name === field || field.startsWith(f.name + '.'))
}

Type guard

function isValidField(cfg, field): boolean {
  return !!getFieldByPath({ fields: cfg.flattenedFields, path: field })
}

Prevention

Validate field names against the collection schema before distinct.
Build distinct calls from known field lists.

When it happens

Trigger: `findDistinct` (or `/distinct?field=foo`) where `foo` is not a defined field on the collection, is misspelled, or is a dotted relationship path that does not resolve.

Common situations: Typo in the field name; field renamed in a config change; querying a relationship sub-field with the wrong path; field exists only on a different collection.

Related errors

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