From c5420d8631d48063218a293675ecb58c6900f8cf Mon Sep 17 00:00:00 2001 From: Alessio Gravili Date: Tue, 5 Aug 2025 19:53:18 -0700 Subject: [PATCH 1/3] Initial Docs --- docs/troubleshooting/troubleshooting.mdx | 54 ++++++++++++++++++++++++ 1 file changed, 54 insertions(+) diff --git a/docs/troubleshooting/troubleshooting.mdx b/docs/troubleshooting/troubleshooting.mdx index 3137d930e0a..c6c551cd2bd 100644 --- a/docs/troubleshooting/troubleshooting.mdx +++ b/docs/troubleshooting/troubleshooting.mdx @@ -23,3 +23,57 @@ 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. + +### Errors due to dependency management + +All `payload` and `@payloadcms/*` packages need to be on the same version and be installed only once. If you have mismatching versions or multiple copies of the same package installed, you may run into issues. + +The most common issues are React hooks no longer working, as one package may use a hook from one version of `payloadcms/ui`, while the provider of that hook is from another version of `@payloadcms/ui`. Most of the time, this results in the following error, as the `useConfig` hook is the most commonly used hook: `TypeError: Cannot destructure property 'config' of...`. + +In order to check if you have multiple copies of the same package installed, you can run the following command in your terminal: + +```bash +pnpm why @payloadcms/ui +``` + +This will show you the dependency tree for the `@payloadcms/ui` package, and you can see if there are multiple versions installed. This command does not always show you whether you have multiple copies of the same package installed, so you may also want to check your `node_modules` directory manually: + +```bash +find node_modules -name package.json -exec grep -H '"name": "@payloadcms/ui"' {} \; +``` + +As most of these results may be symlinks that reference the same package, you can modify the package.json to figure out if they are actually different versions. The same issue may also occur with `react` and `react-dom`, so you may want to check those as well. + + + Do note that `@payloadcms/ui` actually ships with 2 versions of `@payloadcms/ui` in the same package. Only the following imports can be used within the Payload Admin UI: + +- `@payloadcms/ui` +- `@payloadcms/ui/rsc` +- `@payloadcms/ui/shared` + +All the remaining exports, such as `@payloadcms/ui/elements/...` should **only** be used in your own frontend, outside of the Payload Admin Panel. These exports contain the unbundled version of `@payloadcms/ui` which can help reduce bundle size in your own frontend, if you only need a few components from `@payloadcms/ui`. + + + +#### Fixing dependency issues + +If you are using mismatching or multiple versions of the same `payload` / `@payloadcms/*` / `react` / `react-dom` package, try the following steps: + +1. In your package.json, remove the `^` or `~` from the version of all `payload`, `@payloadcms/*`, `react` and `react-dom` packages. This will ensure that you are always using the exact same version. These prefixes often cause your package manager to install different versions of the same package, which can lead to issues. The payload team recommends not using these prefixes _at all_, as those are mostly useful for npm libraries. +2. Delete your `node_modules` directory. This directory can be easily regenerated by your package manager. Often, when you delete old packages, your package manager won't actually remove them from the `node_modules` directory, which can lead to issues. +3. Run your package manager's install command (e.g. `pnpm install`) to regenerate the `node_modules` directory + +If this issue still happens, do the following: + +1. (If using pnpm, run `pnpm store prune` to remove old packages from the store) +2. Delete the lockfile (e.g. `package-lock.json` or `pnpm-lock.yaml`). This often fixes all dependency mismatch errors. 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 changes before +3. Run your package manager's install command again (e.g. `pnpm install`). +4. If you are still having issues, try running `pnpm dedupe` to remove duplicate packages from the dependency tree. This may help resolve issues with mismatched versions of the same package. + +If the issue still occurs and you're using a package manager other than pnpm, we suggest switching to pnpm. This is what the payload team uses internally, and its symlinking often helps with deduplicating packages. + +You may also need to manually inspect your lockfile and adjust versions of your packages to ensure peer dependencies are met. Sometimes, certain combinations of dependencies and their peer dependencies may cause pnpm to install multiple copies of the same package. Additionally, you may want to inspect your `.npmrc` (if present) and adjust your pnpm settings there. + +Another tool that may help deduplicating packages and fixing dependency issues is [Syncpack](https://www.npmjs.com/package/syncpack). + +As a last resort, you can try using webpack aliases to force certain packages to use a specific version. From f317dede9e5a32063854af4955248c76f717a329 Mon Sep 17 00:00:00 2001 From: Alessio Gravili Date: Tue, 5 Aug 2025 20:34:11 -0700 Subject: [PATCH 2/3] final docs --- docs/troubleshooting/troubleshooting.mdx | 123 +++++++++++++++-------- 1 file changed, 83 insertions(+), 40 deletions(-) diff --git a/docs/troubleshooting/troubleshooting.mdx b/docs/troubleshooting/troubleshooting.mdx index c6c551cd2bd..e82d022d4b6 100644 --- a/docs/troubleshooting/troubleshooting.mdx +++ b/docs/troubleshooting/troubleshooting.mdx @@ -6,74 +6,117 @@ desc: Troubleshooting Common Issues in Payload keywords: admin, components, custom, customize, documentation, Content Management System, cms, headless, javascript, node, react, nextjs, troubleshooting --- -## Common Issues +## Dependency mismatches -### "Unauthorized, you must be logged in to make this request" when attempting to log in +All `payload` and `@payloadcms/*` packages must be on exactly the same version and installed only once. -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. +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: -### Errors due to dependency management +```bash +TypeError: Cannot destructure property 'config' of... +``` -All `payload` and `@payloadcms/*` packages need to be on the same version and be installed only once. If you have mismatching versions or multiple copies of the same package installed, you may run into issues. +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 one identical version in one location. -The most common issues are React hooks no longer working, as one package may use a hook from one version of `payloadcms/ui`, while the provider of that hook is from another version of `@payloadcms/ui`. Most of the time, this results in the following error, as the `useConfig` hook is the most commonly used hook: `TypeError: Cannot destructure property 'config' of...`. +### Confirm whether duplicates exist -In order to check if you have multiple copies of the same package installed, you can run the following command in your terminal: +**pnpm built-in inspection:** ```bash pnpm why @payloadcms/ui ``` -This will show you the dependency tree for the `@payloadcms/ui` package, and you can see if there are multiple versions installed. This command does not always show you whether you have multiple copies of the same package installed, so you may also want to check your `node_modules` directory manually: +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. + +**Manual check (works with any package manager):** ```bash -find node_modules -name package.json -exec grep -H '"name": "@payloadcms/ui"' {} \; +find node_modules -name package.json \ + -exec grep -H '"name": "@payloadcms/ui"' {} \; ``` -As most of these results may be symlinks that reference the same package, you can modify the package.json to figure out if they are actually different versions. The same issue may also occur with `react` and `react-dom`, so you may want to check those as well. +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. - - Do note that `@payloadcms/ui` actually ships with 2 versions of `@payloadcms/ui` in the same package. Only the following imports can be used within the Payload Admin UI: +#### If no duplicates are found + +`@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` -All the remaining exports, such as `@payloadcms/ui/elements/...` should **only** be used in your own frontend, outside of the Payload Admin Panel. These exports contain the unbundled version of `@payloadcms/ui` which can help reduce bundle size in your own frontend, if you only need a few components from `@payloadcms/ui`. +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`. + +### Fixing depedendency issues - +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. -#### Fixing dependency issues +**1. Pin every critical package to an exact version.** -If you are using mismatching or multiple versions of the same `payload` / `@payloadcms/*` / `react` / `react-dom` package, try the following steps: +In package.json remove `^` or `~` from all versions of: -1. In your package.json, remove the `^` or `~` from the version of all `payload`, `@payloadcms/*`, `react` and `react-dom` packages. This will ensure that you are always using the exact same version. These prefixes often cause your package manager to install different versions of the same package, which can lead to issues. The payload team recommends not using these prefixes _at all_, as those are mostly useful for npm libraries. -2. Delete your `node_modules` directory. This directory can be easily regenerated by your package manager. Often, when you delete old packages, your package manager won't actually remove them from the `node_modules` directory, which can lead to issues. -3. Run your package manager's install command (e.g. `pnpm install`) to regenerate the `node_modules` directory +- `payload` +- `@payloadcms/*` +- `react` +- `react-dom` -If this issue still happens, do the following: +Prefixes allow your package manager to float to a newer minor/patch release, causing mismatches. -1. (If using pnpm, run `pnpm store prune` to remove old packages from the store) -2. Delete the lockfile (e.g. `package-lock.json` or `pnpm-lock.yaml`). This often fixes all dependency mismatch errors. 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 changes before -3. Run your package manager's install command again (e.g. `pnpm install`). -4. If you are still having issues, try running `pnpm dedupe` to remove duplicate packages from the dependency tree. This may help resolve issues with mismatched versions of the same package. +**2. Delete node_modules/.** -If the issue still occurs and you're using a package manager other than pnpm, we suggest switching to pnpm. This is what the payload team uses internally, and its symlinking often helps with deduplicating packages. +Old packages often linger even after you change versions or removed them from your package.json. Deleting node_modules ensures a clean slate. -You may also need to manually inspect your lockfile and adjust versions of your packages to ensure peer dependencies are met. Sometimes, certain combinations of dependencies and their peer dependencies may cause pnpm to install multiple copies of the same package. Additionally, you may want to inspect your `.npmrc` (if present) and adjust your pnpm settings there. +**3. Re-install dependencies.** -Another tool that may help deduplicating packages and fixing dependency issues is [Syncpack](https://www.npmjs.com/package/syncpack). +```bash +pnpm install +``` + +#### If the error persists + +**(pnpm only) Clean the global store** + +```bash +pnpm store prune +``` -As a last resort, you can try using webpack aliases to force certain packages to use a specific version. +**Delete the lockfile (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. + +**Deduplicate anything that slipped through:** + +```bash +pnpm dedupe +``` + +**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](https://www.npmjs.com/package/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. + +## "Unauthorized, you must be logged in to make this request" when attempting to log in + +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. From c4350e9d3270bceeb4cdcf96f1ec751fd4c32f21 Mon Sep 17 00:00:00 2001 From: Alessio Gravili Date: Wed, 6 Aug 2025 07:05:17 -0700 Subject: [PATCH 3/3] Apply suggestions from code review Co-authored-by: Jacob Fletcher --- docs/troubleshooting/troubleshooting.mdx | 24 +++++++++++++++--------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/docs/troubleshooting/troubleshooting.mdx b/docs/troubleshooting/troubleshooting.mdx index e82d022d4b6..cbe122ada48 100644 --- a/docs/troubleshooting/troubleshooting.mdx +++ b/docs/troubleshooting/troubleshooting.mdx @@ -16,11 +16,15 @@ When two copies—or two different versions—of any of these packages (or of `r TypeError: Cannot destructure property 'config' of... ``` -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 one identical version in one location. +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. ### Confirm whether duplicates exist -**pnpm built-in inspection:** +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 ```bash pnpm why @payloadcms/ui @@ -28,7 +32,7 @@ pnpm why @payloadcms/ui 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. -**Manual check (works with any package manager):** +2. Manual check (works with any package manager) ```bash find node_modules -name package.json \ @@ -53,7 +57,7 @@ Any other deep import such as `@payloadcms/ui/elements/Button` should **only** b 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.** +1. Pin every critical package to an exact version In package.json remove `^` or `~` from all versions of: @@ -64,11 +68,11 @@ In package.json remove `^` or `~` from all versions of: Prefixes allow your package manager to float to a newer minor/patch release, causing mismatches. -**2. Delete node_modules/.** +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.** +3. Re-install dependencies ```bash pnpm install @@ -76,13 +80,15 @@ pnpm install #### If the error persists -**(pnpm only) Clean the global store** +1. Clean the global store (pnpm only) ```bash pnpm store prune ``` -**Delete the lockfile (pnpm-lock.yaml, package-lock.json, or yarn.lock)** +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. @@ -90,7 +96,7 @@ While it's best practice to manage dependencies in such a way where the lockfile If you are using a version control system, make sure to commit your lockfile after this step. -**Deduplicate anything that slipped through:** +3. Deduplicate anything that slipped through ```bash pnpm dedupe