Troubleshooting
Fix the common dev-tools failures fast — 404s, stale pages, wrong entry points, chrome swaps, and the enabled security note.
Most failures are one of a handful of wiring mistakes. Find your symptom below.
| Symptom | Cause | Fix |
|---|---|---|
/dev or /api/dev 404s | You're outside development, or enabled: false. That gate is config-time: the endpoints aren't registered at all, and the pages and toolbar read the same value per render. | Run in development. On a deployed build there is no fix by design — see below. |
/api/dev* returns 403 {"error":"Forbidden."} | Not a 404 — the endpoint exists, and your options.access.dev gate denied the request. | Fix the gate, or send whatever it checks for. A 403 never comes from enabled. |
| Dev pages show stale data | Something cached the reads your own dev page makes — the plugin's own pages read live per request and cannot be prerendered (they never render under NODE_ENV=production). | Check your getters, not the plugin. Render <DevPage> inside <Suspense> as in Quickstart step 3. |
Build error importing @pro-laico/payload-dev-tools/next in a layout | Wrong entry point. Three entries, three contexts: . is for payload.config, /toolbar is a React component for layouts, /next boots Payload. Mixing them fails at build time. | Import /next only in the dev page file; keep /toolbar in layouts. |
| Chrome swap does nothing | The resolveDevChrome line is missing; header/footer chips set their cookie but nothing reads it. | Add the resolveDevChrome call to your layout (Quickstart step 4). The override is site-wide in dev by design; the toolbar's Real chip (or ?slot=…&clear=1) is the way back. |
| Toolbar closes when I open the admin | Jumping to the admin is a different root layout, so the panel remounts closed. That's a Next boundary, not a setting. | Add the same <DevToolbar /> line inside <RootLayout> in app/(payload)/layout.tsx. |
| Seed view refuses to seed | The seed plugin's preconditions aren't met: ENABLE_SEED=true in .env.local and a logged-in Payload user. | Set both. The card tells you which one is missing, but it can't remove them. |
These tools are development-only, and that's enforced. enabled can turn them off anywhere and
on anywhere except NODE_ENV=production — a deployed build registers no endpoints, renders no
/dev pages, and shows no toolbar, whatever you pass.
That's deliberate. The snapshot and pages are unauthenticated by default for local convenience, so serving them from a deployment would publish collection counts, slugs, seed state, and which env vars are set to anyone with the URL. It also can't go stale and lie: a page that never renders in a production build can never be prerendered with the build machine's numbers.
options.access.dev remains useful for the case that is supported — a shared dev environment —
where it closes the /api/dev* endpoints. It does not gate the /dev pages, which read
enabled and nothing else.