payloadcms/payload · error · Error

Payload is not installed in this project

Error message

Payload is not installed in this project

What it means

performPayloadPackageUpdate collected all payload/@payloadcms/* entries from dependencies and devDependencies but found no entry whose package name is exactly 'payload'. The main payload package must be present to perform an update.

Source

Thrown at packages/create-payload-app/src/lib/update-payload-in-project.ts:151

    devDependencies?: Record<string, string>
  }
  if (!packageObj.dependencies && !packageObj.devDependencies) {
    throw new Error('No package.json found in this project')
  }

  const dependencyGroups = [packageObj.dependencies, packageObj.devDependencies].filter(
    (dependencies): dependencies is Record<string, string> => Boolean(dependencies),
  )
  const payloadPackageEntries = dependencyGroups.flatMap((dependencies) =>
    Object.entries(dependencies).filter(
      ([packageName]) => packageName === 'payload' || packageName.startsWith('@payloadcms/'),
    ),
  )
  const payloadVersion = payloadPackageEntries.find(
    ([packageName]) => packageName === 'payload',
  )?.[1]
  if (!payloadVersion) {
    throw new Error('Payload is not installed in this project')
  }

  const packageManager = await getPackageManager({ projectDir })
  const latestPayloadVersion = await resolvePackageVersion({ packageName: 'payload', versionOrTag })

  if (payloadPackageEntries.every(([, version]) => version === latestPayloadVersion)) {
    return {
      isUpdated: false,
      message: `Payload v${payloadVersion} is already up to date.`,
      success: true,
    }
  }

  const payloadPackages = payloadPackageEntries
    .map(([packageName]) => packageName)
    .filter((packageName) => packageName.startsWith('@payloadcms/'))
  const packageNames = ['payload', ...new Set(payloadPackages)]
  const packagesToUpdate = packageNames.map(

View on GitHub (pinned to 00c58b35c0)

Solutions

1. Install the core package: run `npm install payload` (or pnpm/yarn/bun equivalent) in the project root.
2. If payload is hoisted in a monorepo, run the update from the workspace that actually declares it, or add it explicitly.
3. Check both dependencies and devDependencies for an entry named exactly 'payload'.
4. If you only intended to add @payloadcms/* plugins, use the init flow instead of update.

Example fix

// before — package.json (no core payload)
{
  "dependencies": {
    "@payloadcms/next": "3.x",
    "@payloadcms/db-mongodb": "3.x"
  }
}

// after
{
  "dependencies": {
    "payload": "3.x",
    "@payloadcms/next": "3.x",
    "@payloadcms/db-mongodb": "3.x"
  }
}

import fse from 'fs-extra'
import path from 'path'

async function assertPayloadInstalled(projectDir: string) {
  const pkg = await fse.readJson(path.resolve(projectDir, 'package.json'))
  const deps = { ...pkg.dependencies, ...pkg.devDependencies }
  if (!deps?.payload) {
    throw new Error('Core `payload` package not found in dependencies/devDependencies')
  }
}

function hasPayload(pkg: unknown): boolean {
  if (typeof pkg !== 'object' || pkg === null) return false
  const p = pkg as { dependencies?: Record<string, string>; devDependencies?: Record<string, string> }
  return Boolean(p.dependencies?.payload || p.devDependencies?.payload)
}

When it happens

Trigger: Running the update flow on a project that has @payloadcms/* packages (e.g. @payloadcms/next, @payloadcms/db-postgres) but is missing the core 'payload' dependency — common in partial/manual installs or workspaces that hoisted payload elsewhere.

Common situations: See trigger scenarios.

Related errors

• No package.json found in this project
• Invalid template given
• Invalid database type given. Valid types are: ${Object.value
• Failed to update Payload packages
• Failed to download: ${url}

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