Skip to content

fix(next): re-throw unhandled errors in DocumentView to prevent blank edit views#16124

Open
litlmike wants to merge 1 commit intopayloadcms:mainfrom
litlmike:fix/document-view-silent-error-swallow
Open

fix(next): re-throw unhandled errors in DocumentView to prevent blank edit views#16124
litlmike wants to merge 1 commit intopayloadcms:mainfrom
litlmike:fix/document-view-silent-error-swallow

Conversation

@litlmike
Copy link
Copy Markdown

@litlmike litlmike commented Apr 1, 2026

Description

When renderDocument throws an error that is neither NEXT_REDIRECT nor not-found, the catch block in DocumentView (packages/next/src/views/Document/index.tsx) logs the error but returns undefined. React renders undefined as empty content inside the Suspense boundary, producing a completely blank edit view with no visible error.

// BEFORE — silent fallthrough returns undefined
export async function DocumentView(props: AdminViewServerProps) {
  try {
    const { Document: RenderedDocument } = await renderDocument(props)
    return RenderedDocument
  } catch (error) {
    if (error?.message === 'NEXT_REDIRECT') { throw error }
    logError({ err: error, payload: props.initPageResult.req.payload })
    if (error.message === 'not-found') { notFound() }
    // ⚠️ Falls through here → returns undefined → blank page
  }
}

The Fix

Add throw error at the end of the catch block so unhandled errors propagate to Next.js error boundaries instead of rendering blank.

This is a one-line fix. The comment block explains why it exists for future maintainers.

Impact

  • No behavior change for Node.js deployments where errors in this path are already not-found or NEXT_REDIRECT
  • Fixes blank edit views on edge runtimes (Cloudflare Workers/Pages, Vercel Edge) where auth-context failures, streaming issues, or missing Node.js APIs produce errors that fall through the unhandled path
  • Error boundaries now render visible errors instead of blank pages, making debugging possible

Root Cause Analysis

On Cloudflare Workers, renderDocument does heavy async work — two Promise.all calls fetching permissions, lock state, versions, and form state. Any of these can fail on edge runtimes due to:

These errors are neither not-found nor NEXT_REDIRECT, so they hit the unhandled path and the function silently returns undefined.

Testing

Added DocumentView.spec.ts with vitest cases verifying:

  1. Unhandled errors are re-thrown (not swallowed)
  2. NEXT_REDIRECT errors propagate correctly
  3. The function never returns undefined

Related Issues

Fixes #15712 — Edit views render blank on Cloudflare Pages (empty RSC Suspense boundaries)
Relates to #14656 — Server Actions lose authentication in Cloudflare Workers environment
Relates to opennextjs/opennextjs-cloudflare#544 — PayloadCMS not working with opennextjs

… edit views

When renderDocument throws an error that is neither 'NEXT_REDIRECT' nor
'not-found', the catch block in DocumentView logs the error but returns
undefined. React renders this as an empty Suspense boundary, producing a
completely blank edit view with no visible error message.

This is especially prevalent on edge runtimes (Cloudflare Workers/Pages)
where auth-context failures, streaming issues, or missing Node.js APIs
cause errors that fall through to the unhandled path.

The fix re-throws unhandled errors so they propagate to Next.js error
boundaries, which render a visible error instead of a blank page.

Fixes payloadcms#15712
Relates to payloadcms#14656
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[BUG] Edit views render blank on Cloudflare Pages - empty RSC Suspense boundaries

1 participant