What causes "Not Found" in payloadcms/payload?

payloadcms/payload · warning · NotFound

Not Found

Error message

Not Found

What it means

In `findVersionByIDOperation`, if the versions query returns no document and there is no where-access constraint, it throws `NotFound`. The version ID does not exist or was purged.

Source

Thrown at packages/payload/src/collections/operations/findVersionByID.ts:126

      versions: true,
    })

    const versionsQuery = await payload.db.findVersions<TData>({
      collection: collectionConfig.slug,
      limit: 1,
      locale: locale!,
      pagination: false,
      req,
      select,
      where: fullWhere,
    })

    let result = versionsQuery.docs[0]!

    if (!result) {
      if (!disableErrors) {
        if (!hasWhereAccess) {
          throw new NotFound(req.t)
        }
        if (hasWhereAccess) {
          throw new Forbidden(req.t)
        }
      }

      return null!
    }

    if (!result.version) {
      // Fallback if not selected
      ;(result as any).version = {}
    }

    // /////////////////////////////////////
    // beforeRead - Collection
    // /////////////////////////////////////

View on GitHub (pinned to 00c58b35c0)

Solutions

Verify the version ID.
Handle 404 in the route, or pass `disableErrors: true` to get `null`.

Example fix

// before
const v = await payload.findVersionByID({ collection: 'posts', id })
// after
const v = await payload.findVersionByID({ collection: 'posts', id, disableErrors: true })
if (!v) return notFound()

Defensive patterns

Strategy: try-catch

Type guard

function isNotFound(e): boolean {
  return e?.statusCode === 404 || e?.name === 'NotFound'
}

Try / catch

try {
  return await payload.findVersionByID({ collection, id })
} catch (e) {
  if (isNotFound(e)) return null
  throw e
}

Prevention

Use `disableErrors: true` for optional version lookups.
Handle 404 on version routes gracefully.

When it happens

Trigger: `findVersionByID` for a version ID that does not exist, was deleted, or was auto-pruned by `versions.maxKept`.

Common situations: Stale version reference; version auto-pruned by a `maxKept` limit; version deleted via cleanup.

Related errors

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