{"record":{"id":"6d167775d8c390b2","repo":"payloadcms/payload","slug":"failed-to-update-payload-packages","errorCode":null,"errorMessage":"Failed to update Payload packages","messagePattern":"Failed to update Payload packages","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/create-payload-app/src/lib/update-payload-in-project.ts","lineNumber":185,"sourceCode":"    .filter((packageName) => packageName.startsWith('@payloadcms/'))\n  const packageNames = ['payload', ...new Set(payloadPackages)]\n  const packagesToUpdate = packageNames.map(\n    (packageName) => `${packageName}@${latestPayloadVersion}`,\n  )\n\n  info(`Using ${packageManager}.\\n`)\n  info(\n    `Updating ${packagesToUpdate.length} Payload packages to v${latestPayloadVersion}...\\n\\n${packageNames.map((packageName) => `  - ${packageName}`).join('\\n')}`,\n  )\n\n  const { success: updateSuccess } = await installPackages({\n    packageManager,\n    packagesToInstall: packagesToUpdate,\n    projectDir,\n  })\n\n  if (!updateSuccess) {\n    throw new Error('Failed to update Payload packages')\n  }\n  info('Payload packages updated successfully.')\n\n  return { isUpdated: true, message: 'Payload updated successfully.', success: true }\n}\n\nfunction resolveTanStackTemplateRoot(): string {\n  return path.basename(path.dirname(dirname)) === 'dist'\n    ? path.resolve(dirname, '../template-tanstack')\n    : path.resolve(dirname, '../../../../templates/blank-tanstack/src')\n}\n","sourceCodeStart":167,"sourceCodeEnd":197,"githubUrl":"https://github.com/payloadcms/payload/blob/00c58b35c0ed348ddc22daabf467b139727214fd/packages/create-payload-app/src/lib/update-payload-in-project.ts#L167-L197","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Re-run the equivalent install command manually (printed just before the throw) to see the package manager's real error output.","If a lockfile conflict is shown, delete lockfile + node_modules and retry, or run the package manager's install/fix command.","Confirm the target version exists: check https://registry.npmjs.org/payload (and @payloadcms/*) for the version/tag.","If behind a registry proxy, ensure it mirrors the requested version and is reachable."],"exampleFix":"// before — fails because 3.99.99 does not exist\n$ npx create-payload-app . --payload-version 3.99.99\n\n// after\n$ npx create-payload-app . --payload-version latest","handlingStrategy":"try-catch","validationCode":"// Validate the target version exists before triggering the install\nasync function versionExists(pkg: string, version: string) {\n  const res = await fetch(`https://registry.npmjs.org/${pkg}/${version}`)\n  return res.status === 200\n}\nif (!(await versionExists('payload', targetVersion))) {\n  throw new Error(`payload@${targetVersion} not published`)\n}","typeGuard":null,"tryCatchPattern":"try {\n  await updatePayloadPackages({ projectDir, versionOrTag })\n} catch (e) {\n  if (e instanceof Error && e.message === 'Failed to update Payload packages') {\n    console.error('Install failed — run the printed install command manually for full output')\n  }\n  throw e\n}","preventionTips":["Resolve and verify the version/tag against the registry before invoking update.","Keep lockfiles in sync; remove node_modules + lockfile and retry on persistent failures.","Use published dist-tags (latest/canary) rather than ad-hoc versions."],"tags":["create-payload-app","cli","package-manager","dependencies","network"],"backgroundTag":null,"analyzedSha":"00c58b35c0ed348ddc22daabf467b139727214fd","analyzedAt":"2026-08-12T20:45:03.758Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}