What causes "Not Found" in payloadcms/payload?

Confirm the id is a version id, not the parent document id.

payloadcms/payload · error · NotFound

Not Found

Error message

Not Found

What it means

Thrown as `new NotFound(req.t)` (HTTP 404) at packages/payload/src/collections/operations/restoreVersion.ts:94 when the database query for a version row with the given `id` returns zero docs. This means the version id does not exist in that collection's versions table (it may never have existed, was deleted, or belongs to another collection).

Source

Thrown at packages/payload/src/collections/operations/restoreVersion.ts:94

    }

    // /////////////////////////////////////
    // Retrieve original raw version
    // /////////////////////////////////////

    const { docs: versionDocs } = await req.payload.db.findVersions({
      collection: collectionConfig.slug,
      limit: 1,
      locale: 'all',
      pagination: false,
      req,
      where: { id: { equals: id } },
    })

    const [rawVersionToRestore] = versionDocs

    if (!rawVersionToRestore) {
      throw new NotFound(req.t)
    }

    const { parent: parentDocID, version: versionToRestoreWithLocales } = rawVersionToRestore

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

    const accessResults = !overrideAccess
      ? await executeAccess(
          { id: parentDocID, slug: collectionConfig.slug, req },
          collectionConfig.access.update,
        )
      : true
    const hasWherePolicy = hasWhereAccessResult(accessResults)

    // /////////////////////////////////////
    // Retrieve document

View on GitHub (pinned to 00c58b35c0)

Solutions

Confirm the id is a version id, not the parent document id.
Verify the version still exists with `payload.findVersionByID({ collection, id })` (or `disableErrors: true`) before calling restoreVersion.
Make sure you are targeting the correct collection slug.

Example fix

// before
await payload.restoreVersion({ collection: 'pages', id }) // id may not exist

// after
const existing = await payload.findVersionByID({ collection: 'pages', id, overrideAccess: true, disableErrors: true })
if (!existing) {
  return res.status(404).json({ error: 'Version not found' })
}
await payload.restoreVersion({ collection: 'pages', id })

Defensive patterns

Strategy: validation

Validate before calling

// Verify the version exists (without throwing) before restoring
const existing = await payload.findVersionByID({
  collection: 'pages',
  id: versionId,
  overrideAccess: true,
  disableErrors: true,
})
if (!existing) {
  throw new Error(`Version '${versionId}' does not exist.`)
}
await payload.restoreVersion({ collection: 'pages', id: versionId })

Type guard

const versionExists = async (payload: Payload, collection: CollectionSlug, id: string | number) => {
  const v = await payload.findVersionByID({ collection, id, overrideAccess: true, disableErrors: true })
  return Boolean(v)
}

Try / catch

try {
  await payload.restoreVersion({ collection: 'pages', id: versionId })
} catch (err) {
  if (err instanceof NotFound) {
    // version id does not exist — tell the client 404
  } else throw err
}

Prevention

Confirm you are passing a version id, not a parent document id.
Refresh version lists in the UI after deletions to avoid stale ids.
Do not pass ids across environments (dev/prod).

When it happens

Trigger: Calling `payload.restoreVersion({ collection: 'pages', id: staleId })` with an id from a deleted version; passing a document id instead of a version id; the version was purged by a retention job; wrong collection (the version exists but under a different slug).

Common situations: Stale id cached in the UI after the version was deleted; copy-paste of a parent doc id where a version id was expected; cross-environment id leakage (dev id used against prod data).

Related errors

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