---
title: "Payload CMS — Troubleshooting Common Issues"
aliases: [payload-troubleshooting, payload-debug, payload-common-errors]
tags: [payloadcms, troubleshooting, dependencies, auth, database, hmr]
sources: [raw/troubleshooting__troubleshooting.md]
created: 2026-05-15
updated: 2026-05-15
---

## Dependency Mismatches

All `payload` and `@payloadcms/*` packages **must be on exactly the same version** and installed only once. Duplicate versions cause broken React context:

```
TypeError: Cannot destructure property 'config' of...
```

### Diagnose duplicates

```bash
# pnpm
pnpm why @payloadcms/ui

# Any package manager
find node_modules -name package.json -exec grep -H '"name": "@payloadcms/ui"' {} \;
```

Check `react` and `react-dom` the same way — a second copy causes identical symptoms.

> **Note:** `@payloadcms/ui` ships two bundles by design — dual paths in pnpm output are normal.

### Correct import paths in Admin Panel

Inside Payload Admin UI, only import from:
- `@payloadcms/ui`
- `@payloadcms/ui/rsc`
- `@payloadcms/ui/shared`

Deep imports like `@payloadcms/ui/elements/Button` are for **your frontend only**, outside of the Admin Panel.

### Fix steps (pnpm)

1. **Pin exact versions** — remove `^` and `~` from `payload`, `@payloadcms/*`, `react`, `react-dom`
2. **Delete `node_modules`**
3. **`pnpm install`**

If still broken:
```bash
pnpm store prune   # clean global store
# Delete lockfile + node_modules, then:
pnpm install
pnpm dedupe
```

Last resort: add Webpack alias `resolve.alias['react'] = path.resolve('./node_modules/react')` until root cause is fixed.

### Monorepos

Monorepo pitfall: package managers hoist dependencies differently per package, causing multiple instances.

- Pin `payload`, `@payloadcms/*`, `next`, `react`, `react-dom` at monorepo root
- Delete `.next/`, `node_modules/`, lockfile, then re-install
- Watch for: `useUploadHandlers must be used within UploadHandlersProvider` — next version mismatch

---

## "Unauthorized" on Login

```
Unauthorized, you must be logged in to make this request
```

Means the auth cookie is not being set or accepted. Check:

- **CORS** — avoid `'*'`; list explicit allowed domains
- **CSRF** — if configured, whitelist your domain
- **Cookie settings** — if `domain` is set, verify it's not misconfigured

### Debug via Network tab

1. Open DevTools → Network tab
2. Perform login
3. Inspect the login response — look for `Set-Cookie` header
4. Browser shows ⚠️ icon if cookie was rejected — hover to read the reason

---

## `--experimental-https` HMR WebSocket Issue

Using `--experimental-https` breaks HMR WebSocket (`ws://` vs `wss://`).

**Fix — simple case:**
```env
USE_HTTPS=true
```

**Fix — dynamic URL:**
```env
PAYLOAD_HMR_URL_OVERRIDE=wss://localhost:3000/_next/webpack-hmr
```

---

## Database Password Encoding

Special characters in DB password cause silent connection failures:

```
Cannot read properties of undefined (reading 'searchParams')
Error: cannot connect to Postgres. Details: ...
```

**Fix:** URI-encode the password:
```js
encodeURIComponent(yourPassword)
```

Set the encoded string in the `DATABASE_URI` connection string.

First verify the connection works outside Payload (e.g. Beekeeper Studio) to rule out network issues.

---

## Key Takeaways

- **Same version, one copy** — any `@payloadcms/*` or `react` duplicate breaks context hooks with cryptic errors
- **pnpm dedupe + store prune** — go-to when re-install alone doesn't fix it
- **Monorepo root deps** — install Payload packages at root level to avoid hoist conflicts
- **Auth "Unauthorized"** — 90% a cookie domain/CORS/CSRF misconfiguration; debug with Network tab
- **HTTPS in dev** — set `USE_HTTPS=true` or `PAYLOAD_HMR_URL_OVERRIDE` to fix HMR WebSocket protocol mismatch
- **DB special chars** — always `encodeURIComponent` passwords with `@`, `#`, `%` etc. in connection strings

---

## Related

- [[wiki/payloadcms/migration-troubleshooting|Migration & Troubleshooting]] — v2→v3 and v3→v4 upgrade issues
- [[wiki/payloadcms/installation|Installation]] — Node/Next.js requirements, create-payload-app
- [[wiki/payloadcms/authentication-cookies|Authentication — Cookie Strategy]] — CORS, CSRF, SameSite config detail
- [[wiki/payloadcms/database-overview|Database — Overview]] — adapter selection, MongoDB vs Postgres
- [[wiki/payloadcms/production-deployment|Production Deployment]] — security checklist, Docker, env config
- [[wiki/payloadcms/environment-vars|Environment Variables]] — `.env` setup

---

## Sources

- `raw/troubleshooting__troubleshooting.md`
- https://payloadcms.com/docs/troubleshooting/troubleshooting
