Update Payload CMS Without Breaking Admin
A dry-run upgrade path for Payload CMS major versions: copy the database to staging, run the codemod, then audit admin overrides, adapters, and plugins before touching production.

How to update payload cms across a major version without breaking the admin panel is less about which command to run and more about what you rehearse before you run it. Payload's own migration overview describes the 3.0 release as a complete replatform of the Admin Panel from a React Router single-page application onto the Next.js App Router — which means 'upgrading' is the polite word for what is, in practice, a frontend migration with a database attached. The upgrade that doesn't break the admin is the one you've already run twice on a copy of production.
How to Update Payload CMS: Rehearse Before You Run
The dry-run path has five stages: pin the old release, copy the database, run the codemod, re-audit every custom admin surface and plugin, then cut over with a fallback. Skipping straight to the codemod is how you find out a custom admin route is gone while a user is mid-edit.
Pin Versions and Copy the Database First
Rollback beats debugging. If you haven't got a byte-for-byte copy of the production database on staging, you are not doing a migration — you're running a live experiment. Pin your current Payload release exactly in package.json, drop the caret, then dump the database.
pg_dump $PROD_DATABASE_URL > prod.dump
psql $STAGING_DATABASE_URL < prod.dumpmongodump --uri=$PROD_MONGO_URI --out=./dump
mongorestore --uri=$STAGING_MONGO_URI ./dumpRun the Codemod, Then Read What It Changed
Payload ships a codemod for major-version config changes — run it, then read the diff like it was written by an intern.
npx @payloadcms/codemod --transform <transform-name>Treat every changed file as a claim, not a conclusion. A codemod rewrites the mechanical parts. It does not know your custom field validation or your bespoke access-control functions.
The Admin Replatform Is the Whole Migration at 3.0
If you're crossing 2.x to 3.x, the admin panel is not a CSS change. The 3.0 Admin Panel is a full replatform onto the Next.js App Router — everything you assumed about the admin being a client-side SPA stops being true. Components now sit on a server/client boundary, routing lives in the App Router, and a custom admin route that worked as a SPA can 404 in the new layout.
Audit Every Admin Component Override Before You Merge
Custom admin components are where upgrades quietly fail. The database can be perfectly healthy while a custom approve button renders as a blank card. Check every custom view and route registered in the admin config, every overridden field component, anything importing admin internals instead of the exported API, and any component touching browser APIs that now needs a client directive.
Update Config and DB Adapters in One Pass
Adapter and config changes usually ride along with the codemod, but verify them by hand — import paths and driver versions are the two things codemods get right most of the time and wrong silently the rest.
Version jump | What changes | What to rehearse |
|---|---|---|
2.x -> 3.x | Admin replatform to Next.js App Router | Custom routes, client/server boundaries, import paths |
2.x -> 3.x | Config and adapter import changes | Run the codemod, verify the DB driver and connection config |
3.x -> 4.x | Further codemod-driven config changes | Re-audit plugins and admin overrides; don't trust the codemod alone |
Payload's database migration commands are available via npm run payload — create a migration for any schema difference the upgrade introduces and verify it on the staging copy.
npm run payload migrate:create
npm run payload migratePlugins: Treat Each One as Its Own Migration
Assume no plugin is compatible until you've read its changelog for the version you're targeting. A plugin that peer-depends on the old admin internals will break the new admin whether or not the core upgrade is clean. For each plugin, check peer-dependency ranges, flag any admin component it injects, and test it in isolation. If you're assembling a plugin set for a Next.js project, we've written about the payload cms plugins we actually install and how to use payload cms with nextjs.
Cut Over With a Rollback Path, Not a Leap of Faith
When the dry run is clean, cut over with the previous release pinned as your fallback. The upgrade becomes a deploy, not a decision — and a deploy can be reverted. The shops doing this work treat the 3-to-4 move once stable lands as maintenance rather than a beta field trip. If you'd rather not own the dry run yourself, we run Payload migrations end to end.
That's the whole playbook for how to update payload cms without breaking the admin: rehearse it on a copy, verify every custom surface, and keep a way back.
FAQ
Should I update Payload CMS to v4 now or stay on v3?
Run the 3-to-4 migration once a stable release is out; betas are for testing the path, not for production workloads.
What breaks in the Payload admin during a major update?
The 3.0 admin replatformed from a React Router SPA onto the Next.js App Router, so custom views, field components, and routes often need rework.
Do I need a staging database to update Payload CMS safely?
Yes. Copy the production database to staging and rehearse the full upgrade there before you touch live data.
Will a codemod update my Payload config automatically?
Payload ships a codemod for major-version config changes, but you still verify adapters, plugins, and admin overrides by hand.