Skip to content

Commit e870be0

Browse files
authored
docs: add dependency troubleshooting docs (#13385)
Dependency mismanagement is the #1 cause of issues people have with payload. This PR adds a details docs section explaining why those issues occur and how to fix them. **[👀 Click here for docs preview](https://payloadcms.com/docs/dynamic/troubleshooting/troubleshooting?branch=docs/dependencies)**
1 parent d4f1986 commit e870be0

File tree

1 file changed

+105
-2
lines changed

1 file changed

+105
-2
lines changed

docs/troubleshooting/troubleshooting.mdx

Lines changed: 105 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,112 @@ desc: Troubleshooting Common Issues in Payload
66
keywords: admin, components, custom, customize, documentation, Content Management System, cms, headless, javascript, node, react, nextjs, troubleshooting
77
---
88

9-
## Common Issues
9+
## Dependency mismatches
1010

11-
### "Unauthorized, you must be logged in to make this request" when attempting to log in
11+
All `payload` and `@payloadcms/*` packages must be on exactly the same version and installed only once.
12+
13+
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:
14+
15+
```bash
16+
TypeError: Cannot destructure property 'config' of...
17+
```
18+
19+
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.
20+
21+
### Confirm whether duplicates exist
22+
23+
The first thing to do is to confirm whether duplicative dependencies do in fact exist.
24+
25+
There are two ways to do this:
26+
27+
1. Using pnpm's built-in inspection tool
28+
29+
```bash
30+
pnpm why @payloadcms/ui
31+
```
32+
33+
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.
34+
35+
2. Manual check (works with any package manager)
36+
37+
```bash
38+
find node_modules -name package.json \
39+
-exec grep -H '"name": "@payloadcms/ui"' {} \;
40+
```
41+
42+
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.
43+
44+
Perform the same two checks for react and react-dom; a second copy of React can cause identical symptoms.
45+
46+
#### If no duplicates are found
47+
48+
`@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:
49+
50+
- `@payloadcms/ui`
51+
- `@payloadcms/ui/rsc`
52+
- `@payloadcms/ui/shared`
53+
54+
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`.
55+
56+
### Fixing depedendency issues
57+
58+
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.
59+
60+
1. Pin every critical package to an exact version
61+
62+
In package.json remove `^` or `~` from all versions of:
63+
64+
- `payload`
65+
- `@payloadcms/*`
66+
- `react`
67+
- `react-dom`
68+
69+
Prefixes allow your package manager to float to a newer minor/patch release, causing mismatches.
70+
71+
2. Delete node_modules
72+
73+
Old packages often linger even after you change versions or removed them from your package.json. Deleting node_modules ensures a clean slate.
74+
75+
3. Re-install dependencies
76+
77+
```bash
78+
pnpm install
79+
```
80+
81+
#### If the error persists
82+
83+
1. Clean the global store (pnpm only)
84+
85+
```bash
86+
pnpm store prune
87+
```
88+
89+
2. Delete the lockfile
90+
91+
Depending on your package manager, this could be `pnpm-lock.yaml`, `package-lock.json`, or `yarn.lock`.
92+
93+
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.
94+
95+
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.
96+
97+
If you are using a version control system, make sure to commit your lockfile after this step.
98+
99+
3. Deduplicate anything that slipped through
100+
101+
```bash
102+
pnpm dedupe
103+
```
104+
105+
**Still stuck?**
106+
107+
- Switch to `pnpm` if you are on npm. Its symlinked store helps reducing accidental duplication.
108+
- Inspect the lockfile directly for peer-dependency violations.
109+
- Check project-level .npmrc / .pnpmfile.cjs overrides.
110+
- Run [Syncpack](https://www.npmjs.com/package/syncpack) to enforce identical versions of every `@payloadcms/*`, `react`, and `react-dom` reference.
111+
112+
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.
113+
114+
## "Unauthorized, you must be logged in to make this request" when attempting to log in
12115

13116
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:
14117

0 commit comments

Comments
 (0)