Troubleshooting

All payload and @payloadcms/* packages must be on exactly the same version and installed only once.

When two copies—or two different versions—of any of these packages (or of react / react-dom) appear in your dependency graph, you can see puzzling runtime errors. The most frequent is a broken React context:

This happens because one package imports a hook (most commonly useConfig) from version A while the context provider comes from version B. The fix is always the same: make sure every Payload-related and React package resolves to the same module.

The first thing to do is to confirm whether duplicative dependencies do in fact exist.

There are two ways to do this:

1. Using pnpm's built-in inspection tool

This prints the dependency tree and shows which versions are being installed. If you see more than one distinct version—or the same version listed under different paths—you have duplication.

2. Manual check (works with any package manager)

Most of these hits are likely symlinks created by pnpm. Edit the matching package.json files (temporarily add a comment or change a description) to confirm whether they point to the same physical folder or to multiple copies.

Perform the same two checks for react and react-dom; a second copy of React can cause identical symptoms.

@payloadcms/ui intentionally contains two bundles of itself, so you may see dual paths even when everything is correct. Inside the Payload Admin UI you must import only:

• @payloadcms/ui
• @payloadcms/ui/rsc
• @payloadcms/ui/shared

Any other deep import such as @payloadcms/ui/elements/Button should only be used in your own frontend, outside of the Payload Admin Panel. Those deep entries are published un-bundled to help you tree-shake and ship a smaller client bundle if you only need a few components from @payloadcms/ui.

These steps assume pnpm, which the Payload team recommends and uses internally. The principles apply to other package managers like npm and yarn as well. Do note that yarn 1.x is not supported by Payload.

1. Pin every critical package to an exact version

In package.json remove ^ or ~ from all versions of:

• payload
• @payloadcms/*
• react
• react-dom

Prefixes allow your package manager to float to a newer minor/patch release, causing mismatches.

2. Delete node_modules

Old packages often linger even after you change versions or removed them from your package.json. Deleting node_modules ensures a clean slate.

3. Re-install dependencies

1. Clean the global store (pnpm only)

2. Delete the lockfile

Depending on your package manager, this could be pnpm-lock.yaml, package-lock.json, or yarn.lock.

Make sure you delete the lockfile and the node_modules folder at the same time, then run pnpm install. This forces a fresh, consistent resolution for all packages. It will also update all packages with dynamic versions to the latest version.

While it's best practice to manage dependencies in such a way where the lockfile can easily be re-generated (often this is the easiest way to resolve dependency issues), this may break your project if you have not tested the latest versions of your dependencies.

If you are using a version control system, make sure to commit your lockfile after this step.

3. Deduplicate anything that slipped through

Still stuck?

• Switch to pnpm if you are on npm. Its symlinked store helps reducing accidental duplication.
• Inspect the lockfile directly for peer-dependency violations.
• Check project-level .npmrc / .pnpmfile.cjs overrides.
• Run Syncpack to enforce identical versions of every @payloadcms/*, react, and react-dom reference.

Absolute last resort: add Webpack aliases so that all imports of a given package resolve to the same path (e.g. resolve.alias['react'] = path.resolve('./node_modules/react')). Keep this only until you can fix the underlying version skew.

This means that your auth cookie is not being set or accepted correctly upon logging in. To resolve check the following settings in your Payload Config:

• CORS - If you are using the '*', try to explicitly only allow certain domains instead including the one you have specified.
• CSRF - Do you have this set? if so, make sure your domain is whitelisted within the csrf domains. If not, probably not the issue, but probably can't hurt to whitelist it anyway.
• Cookie settings. If these are completely undefined, then that's fine. but if you have cookie domain set, or anything similar, make sure you don't have the domain misconfigured

This error likely means that the auth cookie that Payload sets after logging in successfully is being rejected because of misconfiguration.

To further investigate the issue:

• Go to the login screen. Open your inspector. Go to the Network tab.
• Log in and then find the login request that should appear in your network panel. Click the login request.
• The login request should have a Set-Cookie header on the response, and the cookie should be getting set successfully. If it is not, most browsers generally have a little yellow ⚠️ symbol that you can hover over to see why the cookie was rejected.