vault backup: 2026-05-15 16:50:41

wiki/_master-index.md

@@ -35,7 +35,7 @@ This 3-hop pattern works for hundreds of articles without vector search.
 | [[wiki/reports/_index\|reports/]] | Weekly and monthly summaries — generate: `uv run python scripts/report-generator.py --weekly` | 1 |
 | [[wiki/infrastructure/_index\|infrastructure/]] | Server inventory: all 10 SSH hosts — optical, optical-dev, optical-prod, baic, librechat, modocmms, box-cli, aimpress, pve | 12 |
 | [[wiki/testing/_index\|testing/]] | Web app testing: functional, performance, security, UI types; TDD/BDD/Agile methodologies; Selenium/Cypress/Playwright/JMeter/OWASP ZAP tools | 1 |
-| [[wiki/payloadcms/_index\|payloadcms/]] | Full Payload CMS reference — getting started, config, database (Postgres/MongoDB/SQLite), all 22 field types, access control, hooks, authentication (cookies, JWT, API keys, custom strategies, token data), admin UI, custom components, Lexical rich text, live preview, versions/drafts, Local/REST/GraphQL APIs, queries, plugins, jobs queue, upload, ecommerce, production deploy, TypeScript, migration guides, i18n, localization, hierarchy, trash/soft-delete | 141 |
+| [[wiki/payloadcms/_index\|payloadcms/]] | Full Payload CMS reference — getting started, config, database (Postgres/MongoDB/SQLite), all 22 field types, access control, hooks, authentication (cookies, JWT, API keys, custom strategies, token data), admin UI, custom components, Lexical rich text, live preview, versions/drafts, Local/REST/GraphQL APIs, queries, plugins, jobs queue, upload, ecommerce, production deploy, TypeScript, migration guides, i18n, localization, hierarchy, trash/soft-delete, troubleshooting | 142 |
 
 | [[wiki/shared-patterns/_index\|shared-patterns/]] | Oliver Agency standard library patterns: httpx, structlog, pydantic-settings, alembic — reuse before writing from scratch | 4 |
 | [[wiki/mistakes/_index\|mistakes/]] | Anti-patterns extracted from sessions — per-stack running lists (fastapi, react, docker, postgres, general) — injected at session start | 5 |

wiki/payloadcms/_index.md

@@ -142,3 +142,4 @@
 | [[wiki/payloadcms/rich-text-rendering-on-demand\|Rich Text — Rendering On Demand (RenderLexical)]] | `RenderLexical` experimental component: render Lexical editor outside a Form via server action, schemaPath resolution, inside-Form vs controlled-state modes, hidden anchor field tip | raw/rich-text__rendering-on-demand.md | 2026-05-15 |
 | [[wiki/payloadcms/rich-text-views\|Rich Text — Lexical Views]] | Experimental: named rendering modes (default/preview/branded) for Lexical nodes — shared admin panel + JSX converter rendering, view selector UI, Component/createDOM/html overrides, Block/Label keys, bundle-size gotcha | raw/rich-text__views.md | 2026-05-15 |
 | [[wiki/payloadcms/trash-soft-delete\|Trash — Soft Delete]] | `trash: true` on a collection enables soft delete via `deletedAt` timestamp; dedicated Trash admin view; `trash` query param for all APIs; access control differentiates trash vs permanent delete via `data.deletedAt` | raw/trash__overview.md | 2026-05-15 |
+| [[wiki/payloadcms/troubleshooting\|Troubleshooting Common Issues]] | Dependency mismatches (duplicate packages, monorepos), "Unauthorized" cookie debug, --experimental-https HMR WebSocket fix, DB password encoding | raw/troubleshooting__troubleshooting.md | 2026-05-15 |

wiki/payloadcms/troubleshooting.md

@@ -0,0 +1,149 @@
+---
+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