payloadcms/payload · error · Error

Failed to update Payload packages

Error message

Failed to update Payload packages

What it means

performPayloadPackageUpdate called installPackages (the selected package manager's add command with payload@<version> + @payloadcms/*@<version>) and it returned success=false. This is a wrapper that surfaces the package manager's non-zero exit as a thrown Error.

Source

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

    .filter((packageName) => packageName.startsWith('@payloadcms/'))
  const packageNames = ['payload', ...new Set(payloadPackages)]
  const packagesToUpdate = packageNames.map(
    (packageName) => `${packageName}@${latestPayloadVersion}`,
  )

  info(`Using ${packageManager}.\n`)
  info(
    `Updating ${packagesToUpdate.length} Payload packages to v${latestPayloadVersion}...\n\n${packageNames.map((packageName) => `  - ${packageName}`).join('\n')}`,
  )

  const { success: updateSuccess } = await installPackages({
    packageManager,
    packagesToInstall: packagesToUpdate,
    projectDir,
  })

  if (!updateSuccess) {
    throw new Error('Failed to update Payload packages')
  }
  info('Payload packages updated successfully.')

  return { isUpdated: true, message: 'Payload updated successfully.', success: true }
}

function resolveTanStackTemplateRoot(): string {
  return path.basename(path.dirname(dirname)) === 'dist'
    ? path.resolve(dirname, '../template-tanstack')
    : path.resolve(dirname, '../../../../templates/blank-tanstack/src')
}

View on GitHub (pinned to 00c58b35c0)

Solutions

1. Re-run the equivalent install command manually (printed just before the throw) to see the package manager's real error output.
2. If a lockfile conflict is shown, delete lockfile + node_modules and retry, or run the package manager's install/fix command.
3. Confirm the target version exists: check https://registry.npmjs.org/payload (and @payloadcms/*) for the version/tag.
4. If behind a registry proxy, ensure it mirrors the requested version and is reachable.

Example fix

// before — fails because 3.99.99 does not exist
$ npx create-payload-app . --payload-version 3.99.99

// after
$ npx create-payload-app . --payload-version latest

// Validate the target version exists before triggering the install
async function versionExists(pkg: string, version: string) {
  const res = await fetch(`https://registry.npmjs.org/${pkg}/${version}`)
  return res.status === 200
}
if (!(await versionExists('payload', targetVersion))) {
  throw new Error(`payload@${targetVersion} not published`)
}

try {
  await updatePayloadPackages({ projectDir, versionOrTag })
} catch (e) {
  if (e instanceof Error && e.message === 'Failed to update Payload packages') {
    console.error('Install failed — run the printed install command manually for full output')
  }
  throw e
}

When it happens

Trigger: The install command failed: version not resolvable on the registry, peer dependency conflict, lockfile out of sync, disk/permission error, or package manager offline. The preceding info() logs show the exact packages and target version.

Common situations: Targeting a canary/patch version that was unpublished; npm/pnpm peer-dep conflicts when crossing a major; corrupted lockfile; corporate registry mirror missing the version; read-only node_modules.

Related errors

• Failed to download: ${url}
• Failed to download: ${url}
• Payload is not installed in this project
• No version or tag "${version}" found for package: ${packageN
• Invalid template given

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