Add helpful context to postpone reason if it's caught and logged or e…

…scapes (#58222)

Other ways such as on the client.

packages/next/src/client/components/maybe-postpone.ts

@@ -21,5 +21,9 @@ export function maybePostpone(
   // Keep track of if the postpone API has been called.
   staticGenerationStore.postponeWasTriggered = true
 
-  React.unstable_postpone(reason)
+  React.unstable_postpone(
+    `This page needs to opt out of static rendering at this point because it used ` +
+      `${reason}. React throws this special object to bail out. It should not be caught ` +
+      `by your own try/catch. Learn more: https://nextjs.org/docs/messages/ppr-postpone-error`
+  )
 }

test/e2e/app-dir/ppr-errors/app/logging-error/page.jsx

@@ -0,0 +1,20 @@
+import React, { Suspense } from 'react'
+import { cookies } from 'next/headers'
+
+export default async function Page() {
+  return (
+    <Suspense fallback={<div>Loading...</div>}>
+      <Foobar />
+    </Suspense>
+  )
+}
+
+async function Foobar() {
+  try {
+    cookies()
+  } catch (err) {
+    console.log('Logged error: ' + err.message)
+  }
+  cookies() // still postpones so doesn't fail build
+  return null
+}

test/e2e/app-dir/ppr-errors/ppr-errors.test.ts

@@ -2,9 +2,15 @@ import { nextBuild } from 'next-test-utils'
 
 describe('ppr build errors', () => {
   let stderr: string
+  let stdout: string
 
   beforeAll(async () => {
-    stderr = (await nextBuild(__dirname, [], { stderr: true })).stderr
+    const output = await nextBuild(__dirname, [], {
+      stderr: true,
+      stdout: true,
+    })
+    stderr = output.stderr
+    stdout = output.stdout
   })
 
   describe('within a suspense boundary', () => {
@@ -79,4 +85,12 @@ describe('ppr build errors', () => {
       })
     })
   })
+
+  describe('when a postpone call is caught and logged it should', () => {
+    it('should include a message telling why', async () => {
+      expect(stdout).toContain(
+        "Logged error: This page needs to opt out of static rendering at this point because it used Page couldn't be rendered statically because it used `cookies`."
+      )
+    })
+  })
 })