Summary
Payload declares a Next.js peer dependency but does not enforce it at runtime, so installing an unsupported Next version (one in the 16.0.0 to 16.2.5 gap) produces a cryptic admin failure with no hint that the Next version is the cause. A clear startup warning would turn an opaque debugging session into a one line fix.
What happened
- App on
payload@3.85.1 and @payloadcms/next@3.85.1 with next@16.2.1.
@payloadcms/next@3.85.1 declares the next peer as >=15.2.9 <15.3.0 || >=15.3.9 <15.4.0 || >=15.4.11 <15.5.0 || >=16.2.6 <17.0.0, which excludes 16.0.0 to 16.2.5.- pnpm printed an unmet peer warning at install (easy to miss) and installed 16.2.1 anyway.
- The admin panel then rendered a generic "This page could not be found" after login. Nothing pointed at the Next version. Downgrading to a supported version (15.4.11) fixed it instantly.
Current behavior
No startup or build check compares the installed next against the declared peer range. The only version aware message is the Turbopack specific one reworded in #14873.
Proposed behavior
At admin or app startup, compare the resolved next version against the declared peer range. If it falls outside, log a clear, actionable message such as
Payload requires Next.js ">=16.2.6 <17" (or a supported 15.x range). Found 16.2.1, which is unsupported and may contain unpatched security advisories.
Since 16.2.6 was floored for security reasons (#16537), naming the security angle helps users prioritize the upgrade.
Why existing issues do not cover this
Environment
payload 3.85.1, @payloadcms/next 3.85.1, next 16.2.1 (broken) then 15.4.11 (working), Node 23, pnpm.
Suggested labels: enhancement, area: next-payload
Summary
Payload declares a Next.js peer dependency but does not enforce it at runtime, so installing an unsupported Next version (one in the 16.0.0 to 16.2.5 gap) produces a cryptic admin failure with no hint that the Next version is the cause. A clear startup warning would turn an opaque debugging session into a one line fix.
What happened
payload@3.85.1and@payloadcms/next@3.85.1withnext@16.2.1.@payloadcms/next@3.85.1declares thenextpeer as>=15.2.9 <15.3.0 || >=15.3.9 <15.4.0 || >=15.4.11 <15.5.0 || >=16.2.6 <17.0.0, which excludes 16.0.0 to 16.2.5.Current behavior
No startup or build check compares the installed
nextagainst the declared peer range. The only version aware message is the Turbopack specific one reworded in #14873.Proposed behavior
At admin or app startup, compare the resolved
nextversion against the declared peer range. If it falls outside, log a clear, actionable message such asSince 16.2.6 was floored for security reasons (#16537), naming the security angle helps users prioritize the upgrade.
Why existing issues do not cover this
Environment
payload 3.85.1, @payloadcms/next 3.85.1, next 16.2.1 (broken) then 15.4.11 (working), Node 23, pnpm.
Suggested labels:
enhancement,area: next-payload