From 45df362a22a06cd0eb62847632264bbaa1c505de Mon Sep 17 00:00:00 2001 From: Vadym Samoilenko Date: Fri, 15 May 2026 16:50:41 +0100 Subject: [PATCH] vault backup: 2026-05-15 16:50:41 --- .../troubleshooting__troubleshooting.md | 0 .../typescript__generating-types.md | 0 wiki/_master-index.md | 2 +- wiki/payloadcms/_index.md | 1 + wiki/payloadcms/troubleshooting.md | 149 ++++++++++++++++++ 5 files changed, 151 insertions(+), 1 deletion(-) rename raw/{ => _processed}/troubleshooting__troubleshooting.md (100%) rename raw/{ => _processed}/typescript__generating-types.md (100%) create mode 100644 wiki/payloadcms/troubleshooting.md diff --git a/raw/troubleshooting__troubleshooting.md b/raw/_processed/troubleshooting__troubleshooting.md similarity index 100% rename from raw/troubleshooting__troubleshooting.md rename to raw/_processed/troubleshooting__troubleshooting.md diff --git a/raw/typescript__generating-types.md b/raw/_processed/typescript__generating-types.md similarity index 100% rename from raw/typescript__generating-types.md rename to raw/_processed/typescript__generating-types.md diff --git a/wiki/_master-index.md b/wiki/_master-index.md index 4b3e0ba..fde9b01 100644 --- a/wiki/_master-index.md +++ b/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 | diff --git a/wiki/payloadcms/_index.md b/wiki/payloadcms/_index.md index 6ba0460..113ebec 100644 --- a/wiki/payloadcms/_index.md +++ b/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 | diff --git a/wiki/payloadcms/troubleshooting.md b/wiki/payloadcms/troubleshooting.md new file mode 100644 index 0000000..7b64a9b --- /dev/null +++ b/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