Unverified Commit e9bc6190 authored by Aurora Scharff's avatar Aurora Scharff Committed by GitHub

Redesign blocking route dev overlay and build errors (#92638)

### What?

Redesigns the blocking-route error overlay for instant navigation errors
with a distinct "Instant" overlay path, visual technique cards, and
updated error wording framed around navigation impact.

### Why?

The current overlay dumps every possible cause and fix in one block of
text. The new design is friendlier — amber "Instant" badge, a short
headline framed around navigation, and responsive code snippet cards
showing each fix pattern.

### Demo

- **Runtime template** (e.g. `cookies()`):
https://error-messages-overhaul-ibsl.labs.vercel.dev/scenario/26-cookies-ssr-no-instant
- **Dynamic template** (e.g. uncached `fetch`):
https://error-messages-overhaul-ibsl.labs.vercel.dev/scenario/27-fetch-ssr-no-instant

### How?

**Overlay**
- New early-return path in `errors.tsx` for `blocking-route` errors
without refinement — renders `InstantRuntimeError` with CodeFrame →
description → technique cards → CallStack → ErrorCause
- `InstantGuidance` component with responsive CSS grid of fix technique
cards (3 per variant)
- Color-coded cards with colored borders and matching highlight text
(blue, purple, red)
- "Make route params static" card (runtime only) has a dashed border
indicating it's conditional

**Build & CLI messages**
- Build output messages extracted into `blocking-route-messages.ts` and
deduplicated across `dynamic-rendering.ts`
- `dynamicOrRuntimeBodyMessage` added for build-time static validation
where the specific cause can't be pinpointed — lists all APIs
(`fetch(...)`, `cookies()`, `headers()`, `params`, `searchParams`,
`connection()`)
- `isRuntimeVariant()` replaces the old `includes('cookies()')`
heuristic which broke because both templates mention `cookies()`
- `logBuildDebugHint()` extracted and shared between
`logDisallowedDynamicError` and instant validation — adds "run `next
dev`" and "`next build --debug-prerender`" hints to instant validation
build output

Results:
<img width="2094" height="1478" alt="Google Chrome 2026-04-17 16 37 00"
src="https://github.com/user-attachments/assets/04f126c5-250c-4e6e-bad0-d6960496cd13"
/>
<img width="1978" height="1512" alt="Google Chrome 2026-04-17 16 36 37"
src="https://github.com/user-attachments/assets/46a502d8-9500-4055-814b-3efb739949db"
/>

---------
Co-authored-by: 's avatarJanka Uryga <lolzatu2@gmail.com>
parent 9895972d
...@@ -1095,7 +1095,7 @@ ...@@ -1095,7 +1095,7 @@
"1094": "Draft mode cannot be disabled during build-time instant validation.", "1094": "Draft mode cannot be disabled during build-time instant validation.",
"1095": "Route \"%s\" accessed param \"%s\" which is not defined in the \\`samples\\` of \\`unstable_instant\\`. Add it to the sample's \\`params\\` object.", "1095": "Route \"%s\" accessed param \"%s\" which is not defined in the \\`samples\\` of \\`unstable_instant\\`. Add it to the sample's \\`params\\` object.",
"1096": "Route \"%s\" accessed %s \"%s\" which is not defined in the \\`samples\\` of \\`unstable_instant\\`. Add it to the sample's \\`%s\\` array%s", "1096": "Route \"%s\" accessed %s \"%s\" which is not defined in the \\`samples\\` of \\`unstable_instant\\`. Add it to the sample's \\`%s\\` array%s",
"1097": "An unexpected error occcured during instant validation", "1097": "An unexpected error occurred during instant validation",
"1098": "Route \"%s\" accessed searchParam \"%s\" which is not defined in the \\`samples\\` of \\`unstable_instant\\`. Add it to the sample's \\`searchParams\\` object, or \\`{ \"%s\": null }\\` if it should be absent.", "1098": "Route \"%s\" accessed searchParam \"%s\" which is not defined in the \\`samples\\` of \\`unstable_instant\\`. Add it to the sample's \\`searchParams\\` object, or \\`{ \"%s\": null }\\` if it should be absent.",
"1099": "createPrerenderParamsForClientSegment should not be called in validation contexts.", "1099": "createPrerenderParamsForClientSegment should not be called in validation contexts.",
"1100": "Stopping prerender due to instant validation errors.", "1100": "Stopping prerender due to instant validation errors.",
...@@ -1162,5 +1162,12 @@ ...@@ -1162,5 +1162,12 @@
"1161": "\"unstable_prefetch\" is a route segment config and can only be used when the segment is a Server Component module. Remove the \"use client\" directive from \"%s\" to use this API.", "1161": "\"unstable_prefetch\" is a route segment config and can only be used when the segment is a Server Component module. Remove the \"use client\" directive from \"%s\" to use this API.",
"1162": "Route \"%s\" cannot use \\`export const unstable_instant = ...\\` without enabling \\`cacheComponents\\`.", "1162": "Route \"%s\" cannot use \\`export const unstable_instant = ...\\` without enabling \\`cacheComponents\\`.",
"1163": "Unexpected cache miss after cache warming phase during prerendering. This is likely caused by non-deterministic arguments that differ between the cache warming phase and the final prerender phase (e.g. unstable array order). Ensure that arguments passed to cached functions are deterministic.", "1163": "Unexpected cache miss after cache warming phase during prerendering. This is likely caused by non-deterministic arguments that differ between the cache warming phase and the final prerender phase (e.g. unstable array order). Ensure that arguments passed to cached functions are deterministic.",
"1164": "Response body exceeded maximum size of %s bytes" "1164": "Route \"%s\": Next.js encountered uncached data during the initial render.\\n\\n\\`fetch(...)\\` or \\`connection()\\` accessed outside of \\`<Suspense>\\` blocks navigation, leading to a slower user experience.\\n\\nWays to fix this:\\n - Cache the data access with \\`\"use cache\"\\`\\n - Move the data access into a child component within a <Suspense> boundary\\n - Set \\`export const instant = false\\` to allow a blocking route\\n\\nLearn more: https://nextjs.org/docs/messages/blocking-route",
"1165": "Route \"%s\": Next.js encountered runtime data such as \\`cookies()\\`, \\`headers()\\`, \\`params\\`, or \\`searchParams\\` inside \\`generateViewport\\`. This delays the entire page from rendering, resulting in a slow user experience. Learn more: https://nextjs.org/docs/messages/next-prerender-dynamic-viewport",
"1166": "Route \"%s\": Next.js encountered runtime data during the initial render.\\n\\n\\`cookies()\\`, \\`headers()\\`, \\`params\\`, or \\`searchParams\\` accessed outside of \\`<Suspense>\\` blocks navigation, leading to a slower user experience.\\n\\nWays to fix this:\\n - Move the data access into a child component within a <Suspense> boundary\\n - Use \\`generateStaticParams\\` to make route params static\\n - Set \\`export const instant = false\\` to allow a blocking route\\n\\nLearn more: https://nextjs.org/docs/messages/blocking-route",
"1167": "Route \"%s\": Next.js encountered uncached data such as \\`fetch(...)\\` or \\`connection()\\` inside \\`generateViewport\\`. This delays the entire page from rendering, resulting in a slow user experience. Learn more: https://nextjs.org/docs/messages/next-prerender-dynamic-viewport",
"1168": "Route \"%s\": Next.js encountered runtime data such as \\`cookies()\\`, \\`headers()\\`, \\`params\\`, or \\`searchParams\\` inside \\`generateMetadata\\`, or you have file-based metadata such as icons that depend on dynamic params segments. Except for this instance, the page would have been entirely prerenderable which may have been the intended behavior. See more info here: https://nextjs.org/docs/messages/next-prerender-dynamic-metadata",
"1169": "Route \"%s\": Next.js encountered uncached or runtime data during the initial render.\\n\\n\\`fetch(...)\\`, \\`cookies()\\`, \\`headers()\\`, \\`params\\`, \\`searchParams\\`, or \\`connection()\\` accessed outside of \\`<Suspense>\\` blocks navigation, leading to a slower user experience.\\n\\nWays to fix this:\\n - Cache the data access with \\`\"use cache\"\\`\\n - Move the data access into a child component within a <Suspense> boundary\\n - Use \\`generateStaticParams\\` to make route params static\\n - Set \\`export const instant = false\\` to allow a blocking route\\n\\nLearn more: https://nextjs.org/docs/messages/blocking-route",
"1170": "Route \"%s\": Next.js encountered uncached data such as \\`fetch(...)\\` or \\`connection()\\` inside \\`generateMetadata\\`. Except for this instance, the page would have been entirely prerenderable which may have been the intended behavior. See more info here: https://nextjs.org/docs/messages/next-prerender-dynamic-metadata",
"1171": "Response body exceeded maximum size of %s bytes"
} }
...@@ -26,14 +26,15 @@ export function ErrorMessage({ errorMessage, errorType }: ErrorMessageProps) { ...@@ -26,14 +26,15 @@ export function ErrorMessage({ errorMessage, errorType }: ErrorMessageProps) {
// The "Blocking Route" error message is specifically formatted to look nice // The "Blocking Route" error message is specifically formatted to look nice
// in the overlay (rather than just passed through from the console), so we // in the overlay (rather than just passed through from the console), so we
// intentionally don't truncate it and rely on the scroll overflow instead. // intentionally don't truncate it and rely on the scroll overflow instead.
const shouldTruncate = isTooTall && errorType !== 'Blocking Route' const shouldTruncate =
isTooTall && errorType !== 'Blocking Route' && errorType !== 'Instant'
return ( return (
<div className="nextjs__container_errors_wrapper"> <div className="nextjs__container_errors_wrapper">
<div <div
ref={messageRef} ref={messageRef}
id="nextjs__container_errors_desc" id="nextjs__container_errors_desc"
className={`nextjs__container_errors_desc ${shouldTruncate && !isExpanded ? 'truncated' : ''}`} className={`nextjs__container_errors_desc ${shouldTruncate && !isExpanded ? 'truncated' : ''} ${errorType === 'Instant' ? 'nextjs__container_errors_desc_instant' : ''}`}
> >
{errorMessage} {errorMessage}
</div> </div>
...@@ -71,6 +72,10 @@ export const styles = ` ...@@ -71,6 +72,10 @@ export const styles = `
white-space: pre-wrap; white-space: pre-wrap;
} }
.nextjs__container_errors_desc.nextjs__container_errors_desc_instant {
color: var(--color-gray-900);
}
.nextjs__container_errors_desc.truncated { .nextjs__container_errors_desc.truncated {
max-height: 200px; max-height: 200px;
overflow: hidden; overflow: hidden;
......
...@@ -5,6 +5,7 @@ export type ErrorType = ...@@ -5,6 +5,7 @@ export type ErrorType =
| `Recoverable ${string}` | `Recoverable ${string}`
| 'Blocking Route' | 'Blocking Route'
| 'Ambiguous Metadata' | 'Ambiguous Metadata'
| 'Instant'
type ErrorTypeLabelProps = { type ErrorTypeLabelProps = {
errorType: ErrorType errorType: ErrorType
...@@ -14,7 +15,7 @@ export function ErrorTypeLabel({ errorType }: ErrorTypeLabelProps) { ...@@ -14,7 +15,7 @@ export function ErrorTypeLabel({ errorType }: ErrorTypeLabelProps) {
return ( return (
<span <span
id="nextjs__container_errors_label" id="nextjs__container_errors_label"
className={`nextjs__container_errors_label ${errorType === 'Blocking Route' || errorType === 'Ambiguous Metadata' ? 'nextjs__container_errors_label_blocking_page' : ''}`} className={`nextjs__container_errors_label ${errorType === 'Blocking Route' || errorType === 'Ambiguous Metadata' ? 'nextjs__container_errors_label_blocking_page' : ''} ${errorType === 'Instant' ? 'nextjs__container_errors_label_instant' : ''}`}
> >
{errorType} {errorType}
</span> </span>
...@@ -38,4 +39,11 @@ export const styles = ` ...@@ -38,4 +39,11 @@ export const styles = `
background: var(--color-blue-100); background: var(--color-blue-100);
color: var(--color-blue-900); color: var(--color-blue-900);
} }
.nextjs__container_errors_label_instant {
background: var(--color-amber-200);
color: var(--color-amber-900);
font-family: var(--font-stack-sans);
font-weight: 500;
}
` `
import { css } from '../../utils/css'
const DOCS = 'https://nextjs.org/docs/messages/blocking-route'
type CardColor = 'blue' | 'purple' | 'red'
type FixCard = {
title: string
color: CardColor
snippets: Snippet[]
conditional?: boolean
}
type Snippet = {
text: string
highlight?: boolean
}
const runtimeCards: FixCard[] = [
{
title: 'Move within Suspense',
color: 'purple',
snippets: [
{ text: '<Suspense fallback={…}>', highlight: true },
{ text: ' <DataChild />' },
{ text: '</Suspense>', highlight: true },
],
},
{
title: 'Make route params static',
color: 'blue',
conditional: true,
snippets: [
{ text: 'export async function' },
{ text: ' generateStaticParams() {', highlight: true },
{ text: ' return [{ slug: "…" }]' },
{ text: '}' },
],
},
{
title: 'Allow blocking route',
color: 'red',
snippets: [
{ text: 'export const instant = false', highlight: true },
{ text: '' },
{ text: 'export default async function Page() {' },
],
},
]
const dynamicCards: FixCard[] = [
{
title: 'Cache dynamic data',
color: 'blue',
snippets: [
{ text: 'async function getData() {' },
{ text: ' "use cache"', highlight: true },
{ text: ' return db.query(…)' },
{ text: '}' },
],
},
{
title: 'Move within Suspense',
color: 'purple',
snippets: [
{ text: '<Suspense fallback={…}>', highlight: true },
{ text: ' <DataChild />' },
{ text: '</Suspense>', highlight: true },
],
},
{
title: 'Allow blocking route',
color: 'red',
snippets: [
{ text: 'export const instant = false', highlight: true },
{ text: '' },
{ text: 'export default async function Page() {' },
],
},
]
function CardGrid({ cards }: { cards: FixCard[] }) {
return (
<div data-nextjs-card-grid>
{cards.map((card) => (
<div
data-nextjs-fix-card
data-card-color={card.color}
data-card-conditional={card.conditional || undefined}
key={card.title}
>
<pre data-nextjs-fix-snippet>
{card.snippets.map((s, i) => (
<span
key={i}
data-snippet-line
data-snippet-highlight={s.highlight || undefined}
>
{s.text}
{'\n'}
</span>
))}
</pre>
<span data-nextjs-fix-card-title>{card.title}</span>
</div>
))}
</div>
)
}
export function InstantGuidance({
variant,
}: {
variant: 'runtime' | 'navigation'
}) {
const cards = variant === 'navigation' ? dynamicCards : runtimeCards
return (
<div data-nextjs-instant-guidance>
<p data-nextjs-instant-explanation>
This blocks navigation, leading to a slower user experience.{' '}
<a href={DOCS} target="_blank" rel="noopener noreferrer">
Learn more
</a>
</p>
<p data-nextjs-instant-fix-heading>Ways to fix this:</p>
<CardGrid cards={cards} />
</div>
)
}
export const INSTANT_GUIDANCE_STYLES = css`
[data-nextjs-instant-guidance] {
margin-top: 16px;
padding: 0 16px 16px;
}
[data-nextjs-instant-explanation] {
font-size: var(--size-14);
line-height: var(--size-20);
color: var(--color-gray-900);
margin: 0 0 16px;
}
[data-nextjs-instant-explanation] a {
color: var(--color-blue-900);
text-decoration: none;
}
[data-nextjs-instant-explanation] a:hover {
text-decoration: underline;
}
[data-nextjs-instant-fix-heading] {
font-size: var(--size-14);
font-weight: 400;
color: var(--color-gray-900);
margin: 0 0 20px;
padding-top: 16px;
border-top: 1px solid var(--color-gray-alpha-400);
}
/* ── Grid ───────────────────────────────────── */
[data-nextjs-card-grid] {
display: grid;
grid-template-columns: repeat(auto-fill, minmax(250px, 1fr));
gap: 12px;
}
/* ── Card ─────────────────────────────────────── */
[data-nextjs-fix-card] {
min-width: 0;
overflow: hidden;
}
[data-nextjs-fix-card-title] {
display: block;
margin-top: 10px;
font-size: var(--size-13);
color: var(--color-gray-900);
text-align: center;
}
[data-card-conditional] [data-nextjs-fix-snippet] {
border-style: dashed;
}
/* ── Snippet ──────────────────────────────────── */
[data-nextjs-fix-snippet] {
font-family: var(--font-stack-monospace);
font-size: 11.5px;
line-height: 1.6;
margin: 0;
padding: 14px;
white-space: pre;
overflow: hidden;
background: var(--color-background-200);
border: 1px solid var(--color-gray-alpha-400);
border-radius: var(--rounded-lg);
height: 100px;
display: flex;
flex-direction: column;
justify-content: center;
text-align: left;
}
/* ── Card colors (border + highlight text only) ── */
[data-card-color='blue'] [data-nextjs-fix-snippet] {
border-color: var(--color-instant-border-blue);
}
[data-card-color='purple'] [data-nextjs-fix-snippet] {
border-color: var(--color-instant-border-purple);
}
[data-card-color='red'] [data-nextjs-fix-snippet] {
border-color: var(--color-instant-border-red);
}
[data-snippet-line] {
display: block;
color: var(--color-gray-800);
}
[data-snippet-line][data-snippet-highlight] {
color: var(--color-gray-1000);
font-weight: 500;
}
[data-card-color='blue'] [data-snippet-line][data-snippet-highlight] {
color: var(--color-blue-800);
}
[data-card-color='purple'] [data-snippet-line][data-snippet-highlight] {
color: var(--color-instant-text-purple);
}
[data-card-color='red'] [data-snippet-line][data-snippet-highlight] {
color: var(--color-red-800);
}
`
...@@ -20,6 +20,11 @@ import type { HydrationErrorState } from '../../shared/hydration-error' ...@@ -20,6 +20,11 @@ import type { HydrationErrorState } from '../../shared/hydration-error'
import { useActiveRuntimeError } from '../hooks/use-active-runtime-error' import { useActiveRuntimeError } from '../hooks/use-active-runtime-error'
import { formatCodeFrame } from '../components/code-frame/parse-code-frame' import { formatCodeFrame } from '../components/code-frame/parse-code-frame'
import stripAnsi from 'next/dist/compiled/strip-ansi' import stripAnsi from 'next/dist/compiled/strip-ansi'
import { InstantGuidance } from '../components/instant/instant-guidance'
import { CodeFrame } from '../components/code-frame/code-frame'
import { ErrorOverlayCallStack } from '../components/errors/error-overlay-call-stack/error-overlay-call-stack'
import { ErrorCause } from './runtime-error/error-cause'
import { useFrames } from '../utils/get-error-by-type'
interface ErrorsProps extends ErrorBaseProps { interface ErrorsProps extends ErrorBaseProps {
getSquashedHydrationErrorDetails: (error: Error) => HydrationErrorState | null getSquashedHydrationErrorDetails: (error: Error) => HydrationErrorState | null
...@@ -442,6 +447,9 @@ export function getErrorTypeLabel( ...@@ -442,6 +447,9 @@ export function getErrorTypeLabel(
errorDetails: ErrorDetails errorDetails: ErrorDetails
): ErrorOverlayLayoutProps['errorType'] { ): ErrorOverlayLayoutProps['errorType'] {
if (errorDetails.type === 'blocking-route') { if (errorDetails.type === 'blocking-route') {
if (errorDetails.refinement === '') {
return `Instant`
}
return `Blocking Route` return `Blocking Route`
} }
if (errorDetails.type === 'dynamic-metadata') { if (errorDetails.type === 'dynamic-metadata') {
...@@ -546,15 +554,70 @@ function getHydrationErrorDetails( ...@@ -546,15 +554,70 @@ function getHydrationErrorDetails(
} }
} }
function InstantRuntimeError({
error,
variant,
dialogResizerRef,
}: {
error: ReadyRuntimeError
variant: 'runtime' | 'navigation'
dialogResizerRef: React.RefObject<HTMLDivElement | null>
}) {
const frames = useFrames(error)
const firstFrame = useMemo(() => {
const idx = frames.findIndex(
(entry) =>
!entry.ignored &&
Boolean(entry.originalCodeFrame) &&
Boolean(entry.originalStackFrame)
)
return frames[idx] ?? null
}, [frames])
return (
<>
{firstFrame && (
<CodeFrame
stackFrame={firstFrame.originalStackFrame!}
codeFrame={firstFrame.originalCodeFrame!}
/>
)}
<InstantGuidance variant={variant} />
{frames.length > 0 && (
<ErrorOverlayCallStack
dialogResizerRef={dialogResizerRef}
frames={frames}
/>
)}
{/* Instant errors are always single errors, never AggregateError.
Each blocking data access is tracked individually via
dynamicValidation.dynamicErrors and surfaced one at a time. */}
{error.cause && (
<ErrorCause cause={error.cause} dialogResizerRef={dialogResizerRef} />
)}
</>
)
}
function isRuntimeVariant(message: string): boolean {
// Discriminates between `createRuntimeBodyError` and `createDynamicBodyError`
return (
message.includes('encountered runtime data') &&
!message.includes('encountered uncached data')
)
}
function getBlockingRouteErrorDetails(error: Error): null | ErrorDetails { function getBlockingRouteErrorDetails(error: Error): null | ErrorDetails {
const isBlockingPageLoadError = error.message.includes('/blocking-route') const isBlockingPageLoadError = error.message.includes('/blocking-route')
if (isBlockingPageLoadError) { if (isBlockingPageLoadError) {
const isRuntimeData = error.message.includes('cookies()')
return { return {
type: 'blocking-route', type: 'blocking-route',
variant: isRuntimeData ? 'runtime' : 'navigation', variant: isRuntimeVariant(error.message) ? 'runtime' : 'navigation',
refinement: '', refinement: '',
} }
} }
...@@ -563,10 +626,9 @@ function getBlockingRouteErrorDetails(error: Error): null | ErrorDetails { ...@@ -563,10 +626,9 @@ function getBlockingRouteErrorDetails(error: Error): null | ErrorDetails {
'/next-prerender-dynamic-metadata' '/next-prerender-dynamic-metadata'
) )
if (isDynamicMetadataError) { if (isDynamicMetadataError) {
const isRuntimeData = error.message.includes('cookies()')
return { return {
type: 'dynamic-metadata', type: 'dynamic-metadata',
variant: isRuntimeData ? 'runtime' : 'navigation', variant: isRuntimeVariant(error.message) ? 'runtime' : 'navigation',
} }
} }
...@@ -574,10 +636,9 @@ function getBlockingRouteErrorDetails(error: Error): null | ErrorDetails { ...@@ -574,10 +636,9 @@ function getBlockingRouteErrorDetails(error: Error): null | ErrorDetails {
'/next-prerender-dynamic-viewport' '/next-prerender-dynamic-viewport'
) )
if (isBlockingViewportError) { if (isBlockingViewportError) {
const isRuntimeData = error.message.includes('cookies()')
return { return {
type: 'blocking-route', type: 'blocking-route',
variant: isRuntimeData ? 'runtime' : 'navigation', variant: isRuntimeVariant(error.message) ? 'runtime' : 'navigation',
refinement: 'generateViewport', refinement: 'generateViewport',
} }
} }
...@@ -751,6 +812,37 @@ Next.js version: ${props.versionInfo.installed} (${process.env.__NEXT_BUNDLER})\ ...@@ -751,6 +812,37 @@ Next.js version: ${props.versionInfo.installed} (${process.env.__NEXT_BUNDLER})\
} }
break break
case 'blocking-route': case 'blocking-route':
if (errorDetails.refinement === '') {
return (
<ErrorOverlayLayout
errorCode={errorCode}
errorType={errorType}
errorMessage={
errorDetails.variant === 'runtime'
? 'Next.js encountered runtime data during the initial render.'
: 'Next.js encountered uncached data during the initial render.'
}
onClose={isServerError ? undefined : onClose}
debugInfo={debugInfo}
error={error}
runtimeErrors={runtimeErrors}
activeIdx={activeIdx}
setActiveIndex={setActiveIndex}
dialogResizerRef={dialogResizerRef}
generateErrorInfo={generateErrorInfo}
{...props}
>
<Suspense fallback={<div data-nextjs-error-suspended />}>
<InstantRuntimeError
key={activeError.id.toString()}
error={activeError}
variant={errorDetails.variant}
dialogResizerRef={dialogResizerRef}
/>
</Suspense>
</ErrorOverlayLayout>
)
}
errorMessage = ( errorMessage = (
<BlockingPageLoadErrorDescription <BlockingPageLoadErrorDescription
variant={errorDetails.variant} variant={errorDetails.variant}
......
...@@ -126,6 +126,12 @@ ...@@ -126,6 +126,12 @@
--color-green-900: #297c3b; --color-green-900: #297c3b;
--color-green-1000: #18311e; --color-green-1000: #18311e;
/* Instant Guidance Cards */
--color-instant-border-blue: rgba(0, 112, 243, 0.4);
--color-instant-border-purple: rgba(130, 80, 220, 0.4);
--color-instant-border-red: rgba(229, 72, 77, 0.45);
--color-instant-text-purple: rgb(130, 80, 220);
/* Turbopack Light - Temporary */ /* Turbopack Light - Temporary */
--color-turbopack-text-red: #ff1e56; --color-turbopack-text-red: #ff1e56;
--color-turbopack-text-blue: #0096ff; --color-turbopack-text-blue: #0096ff;
......
...@@ -19,6 +19,7 @@ import { DEV_TOOLS_INFO_USER_PREFERENCES_STYLES } from '../components/errors/dev ...@@ -19,6 +19,7 @@ import { DEV_TOOLS_INFO_USER_PREFERENCES_STYLES } from '../components/errors/dev
import { FADER_STYLES } from '../components/fader' import { FADER_STYLES } from '../components/fader'
import { CALL_STACK_STYLES } from '../components/call-stack/call-stack' import { CALL_STACK_STYLES } from '../components/call-stack/call-stack'
import { SHORTCUT_RECORDER_STYLES } from '../components/errors/dev-tools-indicator/dev-tools-info/shortcut-recorder' import { SHORTCUT_RECORDER_STYLES } from '../components/errors/dev-tools-indicator/dev-tools-info/shortcut-recorder'
import { INSTANT_GUIDANCE_STYLES } from '../components/instant/instant-guidance'
export function ComponentStyles() { export function ComponentStyles() {
return ( return (
...@@ -44,6 +45,7 @@ export function ComponentStyles() { ...@@ -44,6 +45,7 @@ export function ComponentStyles() {
${DEV_TOOLS_INFO_USER_PREFERENCES_STYLES} ${DEV_TOOLS_INFO_USER_PREFERENCES_STYLES}
${FADER_STYLES} ${FADER_STYLES}
${SHORTCUT_RECORDER_STYLES} ${SHORTCUT_RECORDER_STYLES}
${INSTANT_GUIDANCE_STYLES}
`} `}
</style> </style>
) )
......
...@@ -93,6 +93,12 @@ ...@@ -93,6 +93,12 @@
--color-green-900: #63c174; --color-green-900: #63c174;
--color-green-1000: #e5fbeb; --color-green-1000: #e5fbeb;
/* Instant Guidance Cards */
--color-instant-border-blue: rgba(82, 169, 255, 0.45);
--color-instant-border-purple: rgba(160, 120, 240, 0.45);
--color-instant-border-red: rgba(255, 99, 105, 0.4);
--color-instant-text-purple: rgb(160, 120, 240);
/* Turbopack Dark - Temporary */ /* Turbopack Dark - Temporary */
--color-turbopack-text-red: #ff6d92; --color-turbopack-text-red: #ff6d92;
--color-turbopack-text-blue: #45b2ff; --color-turbopack-text-blue: #45b2ff;
...@@ -198,6 +204,12 @@ ...@@ -198,6 +204,12 @@
--color-green-900: #63c174; --color-green-900: #63c174;
--color-green-1000: #e5fbeb; --color-green-1000: #e5fbeb;
/* Instant Guidance Cards */
--color-instant-border-blue: rgba(82, 169, 255, 0.45);
--color-instant-border-purple: rgba(160, 120, 240, 0.45);
--color-instant-border-red: rgba(255, 99, 105, 0.4);
--color-instant-text-purple: rgb(160, 120, 240);
/* Turbopack Dark - Temporary */ /* Turbopack Dark - Temporary */
--color-turbopack-text-red: #ff6d92; --color-turbopack-text-red: #ff6d92;
--color-turbopack-text-blue: #45b2ff; --color-turbopack-text-blue: #45b2ff;
......
...@@ -168,6 +168,7 @@ import { ...@@ -168,6 +168,7 @@ import {
trackThrownErrorInNavigation, trackThrownErrorInNavigation,
createInstantValidationState, createInstantValidationState,
} from './dynamic-rendering' } from './dynamic-rendering'
import { logBuildDebugHint } from './blocking-route-messages'
import { import {
getClientComponentLoaderMetrics, getClientComponentLoaderMetrics,
wrapClientComponentLoader, wrapClientComponentLoader,
...@@ -6627,7 +6628,7 @@ async function validateInstantConfigsInBuild( ...@@ -6627,7 +6628,7 @@ async function validateInstantConfigsInBuild(
} catch (err) { } catch (err) {
console.error( console.error(
new InvariantError( new InvariantError(
'An unexpected error occcured during instant validation', 'An unexpected error occurred during instant validation',
{ cause: err } { cause: err }
) )
) )
...@@ -6737,6 +6738,7 @@ async function validateInstantConfigsInBuildImpl( ...@@ -6737,6 +6738,7 @@ async function validateInstantConfigsInBuildImpl(
console.error( console.error(
`Build-time instant validation failed for route "${route}"${sampleDesc}.` `Build-time instant validation failed for route "${route}"${sampleDesc}.`
) )
logBuildDebugHint(route)
return false return false
} else { } else {
debug?.('✅ Sample validated successfully') debug?.('✅ Sample validated successfully')
......
export function createRuntimeBodyError(route: string): Error {
return new Error(
`Route "${route}": Next.js encountered runtime data during the initial render.\n\n` +
`\`cookies()\`, \`headers()\`, \`params\`, or \`searchParams\` accessed outside of \`<Suspense>\` blocks navigation, leading to a slower user experience.\n\n` +
`Ways to fix this:\n` +
` - Move the data access into a child component within a <Suspense> boundary\n` +
` - Use \`generateStaticParams\` to make route params static\n` +
` - Set \`export const instant = false\` to allow a blocking route\n\n` +
`Learn more: https://nextjs.org/docs/messages/blocking-route`
)
}
export function createDynamicBodyError(route: string): Error {
return new Error(
`Route "${route}": Next.js encountered uncached data during the initial render.\n\n` +
`\`fetch(...)\` or \`connection()\` accessed outside of \`<Suspense>\` blocks navigation, leading to a slower user experience.\n\n` +
`Ways to fix this:\n` +
` - Cache the data access with \`"use cache"\`\n` +
` - Move the data access into a child component within a <Suspense> boundary\n` +
` - Set \`export const instant = false\` to allow a blocking route\n\n` +
`Learn more: https://nextjs.org/docs/messages/blocking-route`
)
}
/**
* NOTE: Prefer `createRuntimeBodyError` or `createDynamicBodyError`.
* Only use this in situations like build-time static validation, where
* we can't pinpoint a more specific reason.
*/
export function createDynamicOrRuntimeBodyError(route: string): Error {
return new Error(
`Route "${route}": Next.js encountered uncached or runtime data during the initial render.\n\n` +
`\`fetch(...)\`, \`cookies()\`, \`headers()\`, \`params\`, \`searchParams\`, or \`connection()\` accessed outside of \`<Suspense>\` blocks navigation, leading to a slower user experience.\n\n` +
`Ways to fix this:\n` +
` - Cache the data access with \`"use cache"\`\n` +
` - Move the data access into a child component within a <Suspense> boundary\n` +
` - Use \`generateStaticParams\` to make route params static\n` +
` - Set \`export const instant = false\` to allow a blocking route\n\n` +
`Learn more: https://nextjs.org/docs/messages/blocking-route`
)
}
export function createRuntimeMetadataError(route: string): Error {
return new Error(
`Route "${route}": Next.js encountered runtime data such as \`cookies()\`, \`headers()\`, \`params\`, or \`searchParams\` inside \`generateMetadata\`, or you have file-based metadata such as icons that depend on dynamic params segments. Except for this instance, the page would have been entirely prerenderable which may have been the intended behavior. See more info here: https://nextjs.org/docs/messages/next-prerender-dynamic-metadata`
)
}
export function createDynamicMetadataError(route: string): Error {
return new Error(
`Route "${route}": Next.js encountered uncached data such as \`fetch(...)\` or \`connection()\` inside \`generateMetadata\`. Except for this instance, the page would have been entirely prerenderable which may have been the intended behavior. See more info here: https://nextjs.org/docs/messages/next-prerender-dynamic-metadata`
)
}
export function createRuntimeViewportError(route: string): Error {
return new Error(
`Route "${route}": Next.js encountered runtime data such as \`cookies()\`, \`headers()\`, \`params\`, or \`searchParams\` inside \`generateViewport\`. This delays the entire page from rendering, resulting in a slow user experience. Learn more: https://nextjs.org/docs/messages/next-prerender-dynamic-viewport`
)
}
export function createDynamicViewportError(route: string): Error {
return new Error(
`Route "${route}": Next.js encountered uncached data such as \`fetch(...)\` or \`connection()\` inside \`generateViewport\`. This delays the entire page from rendering, resulting in a slow user experience. Learn more: https://nextjs.org/docs/messages/next-prerender-dynamic-viewport`
)
}
export function disallowedDynamicViewportMessage(route: string): string {
return `Route "${route}" has a \`generateViewport\` that depends on Request data (\`cookies()\`, etc...) or uncached external data (\`fetch(...)\`, etc...) without explicitly allowing fully dynamic rendering. See more info here: https://nextjs.org/docs/messages/next-prerender-dynamic-viewport`
}
export function disallowedDynamicMetadataMessage(route: string): string {
return `Route "${route}" has a \`generateMetadata\` that depends on Request data (\`cookies()\`, etc...) or uncached external data (\`fetch(...)\`, etc...) when the rest of the route does not. See more info here: https://nextjs.org/docs/messages/next-prerender-dynamic-metadata`
}
export function logBuildDebugHint(route: string): void {
if (process.env.NODE_ENV !== 'development') {
console.error(
`To get a more detailed stack trace and pinpoint the issue, try one of the following:\n` +
` - Start the app in development mode by running \`next dev\`, then open "${route}" in your browser to investigate the error.\n` +
` - Rerun the production build with \`next build --debug-prerender\` to generate better stack traces.`
)
} else if (!process.env.__NEXT_DEV_SERVER) {
console.error(
`To debug the issue, start the app in development mode by running \`next dev\`, then open "${route}" in your browser to investigate the error.`
)
}
}
...@@ -75,12 +75,12 @@ describe('Cache Components Dev Errors', () => { ...@@ -75,12 +75,12 @@ describe('Cache Components Dev Errors', () => {
await openRedbox(browser) await openRedbox(browser)
desc = await getRedboxDescription(browser) desc = await getRedboxDescription(browser)
expect(desc).toContain('https://nextjs.org/docs/messages/blocking-route') expect(desc).toContain('during the initial render')
await browser.refresh() await browser.refresh()
await openRedbox(browser) await openRedbox(browser)
desc = await getRedboxDescription(browser) desc = await getRedboxDescription(browser)
expect(desc).toContain('https://nextjs.org/docs/messages/blocking-route') expect(desc).toContain('during the initial render')
}) })
}) })
...@@ -98,22 +98,10 @@ describe('Cache Components Dev Errors', () => { ...@@ -98,22 +98,10 @@ describe('Cache Components Dev Errors', () => {
await expect(browser).toDisplayCollapsedRedbox(` await expect(browser).toDisplayCollapsedRedbox(`
{ {
"code": "E1084", "code": "E1164",
"description": "Data that blocks navigation was accessed outside of <Suspense> "description": "Next.js encountered uncached data during the initial render.",
This delays the entire page from rendering, resulting in a slow user experience. Next.js uses this error to ensure your app loads instantly on every navigation. Uncached data such as fetch(...), cached data with a low expire time, or connection() are all examples of data that only resolve on navigation.
To fix this, you can either:
Provide a fallback UI using <Suspense> around this component. This allows Next.js to stream its contents to the user as soon as it's ready, without blocking the rest of the app.
or
Move the asynchronous await into a Cache Component ("use cache"). This allows Next.js to statically prerender the component as part of the HTML document, so it's instantly visible to the user.
Learn more: https://nextjs.org/docs/messages/blocking-route",
"environmentLabel": "Server", "environmentLabel": "Server",
"label": "Blocking Route", "label": "Instant",
"source": "app/no-accessed-data/page.js (2:9) @ Page "source": "app/no-accessed-data/page.js (2:9) @ Page
> 2 | await new Promise((r) => setTimeout(r, 200)) > 2 | await new Promise((r) => setTimeout(r, 200))
| ^", | ^",
......
...@@ -105,24 +105,10 @@ describe('instant validation causes', () => { ...@@ -105,24 +105,10 @@ describe('instant validation causes', () => {
], ],
}, },
], ],
"code": "E1078", "code": "E1166",
"description": "Runtime data was accessed outside of <Suspense> "description": "Next.js encountered runtime data during the initial render.",
This delays the entire page from rendering, resulting in a slow user experience. Next.js uses this error to ensure your app loads instantly on every navigation. cookies(), headers(), params, and searchParams are examples of Runtime data that can only come from a user request.
To fix this:
Provide a fallback UI using <Suspense> around this component.
or
Move the Runtime data access into a deeper component wrapped in <Suspense>.
In either case this allows Next.js to stream its contents to the user when they request the page, while still providing an initial UI that is prerendered and prefetchable for instant navigations.
Learn more: https://nextjs.org/docs/messages/blocking-route",
"environmentLabel": "Server", "environmentLabel": "Server",
"label": "Blocking Route", "label": "Instant",
"source": "app/named-export/page.tsx (7:16) @ Page "source": "app/named-export/page.tsx (7:16) @ Page
> 7 | await cookies() > 7 | await cookies()
| ^", | ^",
...@@ -150,24 +136,10 @@ describe('instant validation causes', () => { ...@@ -150,24 +136,10 @@ describe('instant validation causes', () => {
], ],
}, },
], ],
"code": "E1078", "code": "E1166",
"description": "Runtime data was accessed outside of <Suspense> "description": "Next.js encountered runtime data during the initial render.",
This delays the entire page from rendering, resulting in a slow user experience. Next.js uses this error to ensure your app loads instantly on every navigation. cookies(), headers(), params, and searchParams are examples of Runtime data that can only come from a user request.
To fix this:
Provide a fallback UI using <Suspense> around this component.
or
Move the Runtime data access into a deeper component wrapped in <Suspense>.
In either case this allows Next.js to stream its contents to the user when they request the page, while still providing an initial UI that is prerendered and prefetchable for instant navigations.
Learn more: https://nextjs.org/docs/messages/blocking-route",
"environmentLabel": "Server", "environmentLabel": "Server",
"label": "Blocking Route", "label": "Instant",
"source": "app/aliased-export/page.tsx (7:16) @ Page "source": "app/aliased-export/page.tsx (7:16) @ Page
> 7 | await cookies() > 7 | await cookies()
| ^", | ^",
...@@ -195,24 +167,10 @@ describe('instant validation causes', () => { ...@@ -195,24 +167,10 @@ describe('instant validation causes', () => {
], ],
}, },
], ],
"code": "E1078", "code": "E1166",
"description": "Runtime data was accessed outside of <Suspense> "description": "Next.js encountered runtime data during the initial render.",
This delays the entire page from rendering, resulting in a slow user experience. Next.js uses this error to ensure your app loads instantly on every navigation. cookies(), headers(), params, and searchParams are examples of Runtime data that can only come from a user request.
To fix this:
Provide a fallback UI using <Suspense> around this component.
or
Move the Runtime data access into a deeper component wrapped in <Suspense>.
In either case this allows Next.js to stream its contents to the user when they request the page, while still providing an initial UI that is prerendered and prefetchable for instant navigations.
Learn more: https://nextjs.org/docs/messages/blocking-route",
"environmentLabel": "Server", "environmentLabel": "Server",
"label": "Blocking Route", "label": "Instant",
"source": "app/reexport/page.tsx (6:16) @ Page "source": "app/reexport/page.tsx (6:16) @ Page
> 6 | await cookies() > 6 | await cookies()
| ^", | ^",
...@@ -243,24 +201,10 @@ describe('instant validation causes', () => { ...@@ -243,24 +201,10 @@ describe('instant validation causes', () => {
], ],
}, },
], ],
"code": "E1078", "code": "E1166",
"description": "Runtime data was accessed outside of <Suspense> "description": "Next.js encountered runtime data during the initial render.",
This delays the entire page from rendering, resulting in a slow user experience. Next.js uses this error to ensure your app loads instantly on every navigation. cookies(), headers(), params, and searchParams are examples of Runtime data that can only come from a user request.
To fix this:
Provide a fallback UI using <Suspense> around this component.
or
Move the Runtime data access into a deeper component wrapped in <Suspense>.
In either case this allows Next.js to stream its contents to the user when they request the page, while still providing an initial UI that is prerendered and prefetchable for instant navigations.
Learn more: https://nextjs.org/docs/messages/blocking-route",
"environmentLabel": "Server", "environmentLabel": "Server",
"label": "Blocking Route", "label": "Instant",
"source": "app/indirect-export/page.tsx (8:16) @ Page "source": "app/indirect-export/page.tsx (8:16) @ Page
> 8 | await cookies() > 8 | await cookies()
| ^", | ^",
......
...@@ -45,22 +45,10 @@ describe('instant validation', () => { ...@@ -45,22 +45,10 @@ describe('instant validation', () => {
await browser.elementByCss('main') await browser.elementByCss('main')
await expect(browser).toDisplayCollapsedRedbox(` await expect(browser).toDisplayCollapsedRedbox(`
{ {
"code": "E1084", "code": "E1164",
"description": "Data that blocks navigation was accessed outside of <Suspense> "description": "Next.js encountered uncached data during the initial render.",
This delays the entire page from rendering, resulting in a slow user experience. Next.js uses this error to ensure your app loads instantly on every navigation. Uncached data such as fetch(...), cached data with a low expire time, or connection() are all examples of data that only resolve on navigation.
To fix this, you can either:
Provide a fallback UI using <Suspense> around this component. This allows Next.js to stream its contents to the user as soon as it's ready, without blocking the rest of the app.
or
Move the asynchronous await into a Cache Component ("use cache"). This allows Next.js to statically prerender the component as part of the HTML document, so it's instantly visible to the user.
Learn more: https://nextjs.org/docs/messages/blocking-route",
"environmentLabel": "Server", "environmentLabel": "Server",
"label": "Blocking Route", "label": "Instant",
"source": "app/blocking-page-below-static/page.tsx (6:19) @ Page "source": "app/blocking-page-below-static/page.tsx (6:19) @ Page
> 6 | await connection() > 6 | await connection()
| ^", | ^",
...@@ -81,9 +69,7 @@ describe('instant validation', () => { ...@@ -81,9 +69,7 @@ describe('instant validation', () => {
}) })
it('errors during build', () => { it('errors during build', () => {
expect(didBuildError).toBe(true) expect(didBuildError).toBe(true)
expect(next.cliOutput).toContain( expect(next.cliOutput).toContain('during the initial render')
'Uncached data was accessed outside of <Suspense>'
)
}) })
} }
}) })
......
This source diff could not be displayed because it is too large. You can view the blob instead.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment