Restore separate runtime/dynamic error messages and fix cookies() classification

Revert the merged bodyMessage/metadataMessage/viewportMessage back to
separate runtimeBodyMessage/dynamicBodyMessage etc. so the dev overlay
can distinguish runtime APIs from uncached data.

Restore the original isRuntimeVariant detection that matches on
'request-time API', 'cookies()', and 'Runtime data' — the tightened
check broke classification when the second validation pass overrides
with DynamicHoleKind.Dynamic.

Also stamp syncDynamicErrorWithStack errors with runtimeBodyMessage
since sync dynamic errors are always from runtime APIs.

Made-with: Cursor

Author: aurorascharff

packages/next/src/next-devtools/dev-overlay/components/blocking-route-guidance/blocking-route-error-details.ts

@@ -10,14 +10,11 @@ export type DynamicMetadataErrorDetails = {
 }
 
 function isRuntimeVariant(message: string): boolean {
-  if (message.includes('Runtime data')) return true
-  if (
-    message.includes('A request-time API') &&
-    !message.includes('Either a request-time API')
-  ) {
-    return true
-  }
-  return false
+  return (
+    message.includes('request-time API') ||
+    message.includes('cookies()') ||
+    message.includes('Runtime data')
+  )
 }
 
 export function getBlockingRouteErrorDetails(

packages/next/src/server/app-render/blocking-route-messages.ts

@@ -1,4 +1,22 @@
-export function bodyMessage(route: string): string {
+export function runtimeBodyMessage(route: string): string {
+  return (
+    `Route "${route}" can't load instantly.\n\n` +
+    `Cause: A request-time API was used without a surrounding ` +
+    `<Suspense> boundary. This prevents Next.js from prerendering ` +
+    `any part of the page.\n\n` +
+    `Common triggers:\n` +
+    `  - cookies(), headers()\n` +
+    `  - await params, await searchParams\n\n` +
+    `The right fix depends on which API triggered this and what ` +
+    `behavior you want. Possible fixes:\n` +
+    `  - <Suspense>: wrap the dynamic component so the rest loads instantly\n` +
+    `  - Move the API call into a child component wrapped in <Suspense>\n` +
+    `  - loading.js: add a route-level fallback\n\n` +
+    `Learn more: https://nextjs.org/docs/messages/blocking-route`
+  )
+}
+
+export function dynamicBodyMessage(route: string): string {
   return (
     `Route "${route}" can't load instantly.\n\n` +
     `Cause: Uncached data or a request-time API was used without a ` +
@@ -7,8 +25,7 @@ export function bodyMessage(route: string): string {
     `Common triggers:\n` +
     `  - cookies(), headers(), connection()\n` +
     `  - await params, await searchParams\n` +
-    `  - fetch() or database calls without "use cache"\n` +
-    `  - draftMode()\n\n` +
+    `  - fetch() or database calls without "use cache"\n\n` +
     `The right fix depends on which API triggered this and what ` +
     `behavior you want. Possible fixes:\n` +
     `  - <Suspense>: wrap the dynamic component so the rest loads instantly\n` +
@@ -18,7 +35,19 @@ export function bodyMessage(route: string): string {
   )
 }
 
-export function metadataMessage(route: string): string {
+export function runtimeMetadataMessage(route: string): string {
+  return (
+    `Route "${route}" has metadata that blocks loading.\n\n` +
+    `Cause: A request-time API was used inside generateMetadata() ` +
+    `(or you have file-based metadata like icons that depend on ` +
+    `dynamic params). The rest of the page could have been fully ` +
+    `prerendered.\n\n` +
+    `Learn more: ` +
+    `https://nextjs.org/docs/messages/next-prerender-dynamic-metadata`
+  )
+}
+
+export function dynamicMetadataMessage(route: string): string {
   return (
     `Route "${route}" has metadata that blocks loading.\n\n` +
     `Cause: generateMetadata() depends on data that can't be resolved ` +
@@ -29,7 +58,18 @@ export function metadataMessage(route: string): string {
   )
 }
 
-export function viewportMessage(route: string): string {
+export function runtimeViewportMessage(route: string): string {
+  return (
+    `Route "${route}" has viewport config that blocks loading.\n\n` +
+    `Cause: A request-time API was used inside generateViewport(). ` +
+    `Viewport metadata must be available on page load, so this ` +
+    `prevents prerendering.\n\n` +
+    `Learn more: ` +
+    `https://nextjs.org/docs/messages/next-prerender-dynamic-viewport`
+  )
+}
+
+export function dynamicViewportMessage(route: string): string {
   return (
     `Route "${route}" has viewport config that blocks loading.\n\n` +
     `Cause: generateViewport() depends on data that can't be resolved ` +

packages/next/src/server/app-render/dynamic-rendering.ts

@@ -48,9 +48,12 @@ import {
 import { scheduleOnNextTick } from '../../lib/scheduler'
 import { BailoutToCSRError } from '../../shared/lib/lazy-dynamic/bailout-to-csr'
 import {
-  bodyMessage,
-  metadataMessage,
-  viewportMessage,
+  runtimeBodyMessage,
+  dynamicBodyMessage,
+  runtimeMetadataMessage,
+  dynamicMetadataMessage,
+  runtimeViewportMessage,
+  dynamicViewportMessage,
   disallowedDynamicViewportMessage,
   disallowedDynamicMetadataMessage,
 } from './blocking-route-messages'
@@ -817,13 +820,12 @@ export function trackAllowedDynamicAccess(
     dynamicValidation.hasAllowedDynamic = true
     return
   } else if (clientDynamic.syncDynamicErrorWithStack) {
-    // This task was the task that called the sync error.
-    dynamicValidation.dynamicErrors.push(
-      clientDynamic.syncDynamicErrorWithStack
-    )
+    const syncError = clientDynamic.syncDynamicErrorWithStack
+    syncError.message = runtimeBodyMessage(workStore.route)
+    dynamicValidation.dynamicErrors.push(syncError)
     return
   } else {
-    const message = bodyMessage(workStore.route)
+    const message = dynamicBodyMessage(workStore.route)
     const error = addErrorContext(new Error(message), componentStack, null)
     dynamicValidation.dynamicErrors.push(error)
     return
@@ -873,7 +875,7 @@ export function trackDynamicHoleInNavigation(
   componentStack: string,
   dynamicValidation: InstantValidationState,
   clientDynamic: DynamicTrackingState,
-  _kind: DynamicHoleKind,
+  kind: DynamicHoleKind,
   boundaryState: ValidationBoundaryTracking
 ) {
   if (hasOutletRegex.test(componentStack)) {
@@ -889,7 +891,10 @@ export function trackDynamicHoleInNavigation(
   )
 
   if (hasMetadataRegex.test(componentStack)) {
-    const message = metadataMessage(workStore.route)
+    const message =
+      kind === DynamicHoleKind.Runtime
+        ? runtimeMetadataMessage(workStore.route)
+        : dynamicMetadataMessage(workStore.route)
     const error = addErrorContext(
       new Error(message),
       componentStack,
@@ -899,7 +904,10 @@ export function trackDynamicHoleInNavigation(
     return
   }
   if (hasViewportRegex.test(componentStack)) {
-    const message = viewportMessage(workStore.route)
+    const message =
+      kind === DynamicHoleKind.Runtime
+        ? runtimeViewportMessage(workStore.route)
+        : dynamicViewportMessage(workStore.route)
     const error = addErrorContext(
       new Error(message),
       componentStack,
@@ -971,16 +979,19 @@ export function trackDynamicHoleInNavigation(
   }
 
   if (clientDynamic.syncDynamicErrorWithStack) {
-    // This task was the task that called the sync error.
     const syncError = clientDynamic.syncDynamicErrorWithStack
+    syncError.message = runtimeBodyMessage(workStore.route)
     if (effectiveCreateInstantStack !== null && syncError.cause === undefined) {
       syncError.cause = effectiveCreateInstantStack()
     }
     dynamicValidation.dynamicErrors.push(syncError)
     return
   }
 
-  const message = bodyMessage(workStore.route)
+  const message =
+    kind === DynamicHoleKind.Runtime
+      ? runtimeBodyMessage(workStore.route)
+      : dynamicBodyMessage(workStore.route)
   const error = addErrorContext(
     new Error(message),
     componentStack,
@@ -1052,15 +1063,15 @@ export function trackDynamicHoleInRuntimeShell(
     // We don't need to track that this is dynamic. It is only so when something else is also dynamic.
     return
   } else if (hasMetadataRegex.test(componentStack)) {
-    const message = metadataMessage(workStore.route)
+    const message = dynamicMetadataMessage(workStore.route)
     const error = addErrorContext(new Error(message), componentStack, null)
     dynamicValidation.dynamicMetadata = error
     return
   } else if (hasViewportRegex.test(componentStack)) {
     // TODO(instant-validation): If the page only has holes caused by runtime data,
     // we won't find out if there's a suspense-above-body and error for dynamic viewport
     // even if there is in fact a suspense-above-body
-    const message = viewportMessage(workStore.route)
+    const message = dynamicViewportMessage(workStore.route)
     const error = addErrorContext(new Error(message), componentStack, null)
     dynamicValidation.dynamicErrors.push(error)
     return
@@ -1081,14 +1092,13 @@ export function trackDynamicHoleInRuntimeShell(
     dynamicValidation.hasAllowedDynamic = true
     return
   } else if (clientDynamic.syncDynamicErrorWithStack) {
-    // This task was the task that called the sync error.
-    dynamicValidation.dynamicErrors.push(
-      clientDynamic.syncDynamicErrorWithStack
-    )
+    const syncError = clientDynamic.syncDynamicErrorWithStack
+    syncError.message = runtimeBodyMessage(workStore.route)
+    dynamicValidation.dynamicErrors.push(syncError)
     return
   }
 
-  const message = bodyMessage(workStore.route)
+  const message = runtimeBodyMessage(workStore.route)
   const error = addErrorContext(new Error(message), componentStack, null)
   dynamicValidation.dynamicErrors.push(error)
   return
@@ -1104,12 +1114,12 @@ export function trackDynamicHoleInStaticShell(
     // We don't need to track that this is dynamic. It is only so when something else is also dynamic.
     return
   } else if (hasMetadataRegex.test(componentStack)) {
-    const message = metadataMessage(workStore.route)
+    const message = runtimeMetadataMessage(workStore.route)
     const error = addErrorContext(new Error(message), componentStack, null)
     dynamicValidation.dynamicMetadata = error
     return
   } else if (hasViewportRegex.test(componentStack)) {
-    const message = viewportMessage(workStore.route)
+    const message = runtimeViewportMessage(workStore.route)
     const error = addErrorContext(new Error(message), componentStack, null)
     dynamicValidation.dynamicErrors.push(error)
     return
@@ -1130,13 +1140,12 @@ export function trackDynamicHoleInStaticShell(
     dynamicValidation.hasAllowedDynamic = true
     return
   } else if (clientDynamic.syncDynamicErrorWithStack) {
-    // This task was the task that called the sync error.
-    dynamicValidation.dynamicErrors.push(
-      clientDynamic.syncDynamicErrorWithStack
-    )
+    const syncError = clientDynamic.syncDynamicErrorWithStack
+    syncError.message = runtimeBodyMessage(workStore.route)
+    dynamicValidation.dynamicErrors.push(syncError)
     return
   } else {
-    const message = bodyMessage(workStore.route)
+    const message = dynamicBodyMessage(workStore.route)
     const error = addErrorContext(new Error(message), componentStack, null)
     dynamicValidation.dynamicErrors.push(error)
     return