Unverified Commit 2cc99c73 authored by Aurora Scharff's avatar Aurora Scharff Committed by GitHub

docs: move insight error pages from vercel/front to canary (#94564)

### What?

Moves 14 insight-kind error pages from
`vercel/front/apps/next-site/content/errors-extra/` into this repo's
`errors/` directory.

### Why?

`nextjs.org`'s sync pipeline already clones `errors/` from canary on
every deploy. `errors-extra/` is meant for in-flight drafts. These pages
have stabilized, so they belong with the framework code they describe.

This unblocks Docs Link Validation in #94496: cross-links from this
repo's API docs (`cookies.mdx`, `headers.mdx`, `use-params.mdx`,
`use-pathname.mdx`, `generate-metadata.mdx`, `generate-viewport.mdx`,
etc.) to `/docs/messages/blocking-prerender-*` now resolve.

### How?

Copied each `.mdx` verbatim. No content changes. Frontmatter (`kind:
insight`) routes them through the FixOption renderer. Follow-up PR in
`vercel/front` will remove the `errors-extra/` copies; until then the
override wins on slug collision but the content is byte-identical.

<!-- NEXT_JS_LLM_PR -->
parent 5c9bc5c8
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
---
title: Next.js encountered uncached data in generateViewport()
kind: insight
---
During [prerendering](/docs/app/glossary#prerendering), [`generateViewport()`](/docs/app/api-reference/functions/generate-viewport) performed an uncached data access ([`fetch()`](https://developer.mozilla.org/en-US/docs/Web/API/Window/fetch), database call, [`await connection()`](/docs/app/api-reference/functions/connection)). With [Cache Components](/docs/app/api-reference/config/next-config-js/cacheComponents) enabled, viewport metadata can't be deferred behind a [`<Suspense>`](https://react.dev/reference/react/Suspense) boundary because it affects the initial page load. The page can't be prerendered, so navigations block instead of being [instant](/docs/app/guides/instant-navigation).
Request-bound reads ([`cookies()`](/docs/app/api-reference/functions/cookies), [`headers()`](/docs/app/api-reference/functions/headers), [`params`](/docs/app/api-reference/file-conventions/page#params-optional), [`searchParams`](/docs/app/api-reference/file-conventions/page#searchparams-optional)) in `generateViewport()` have different fixes. See [Next.js encountered runtime data in `generateViewport()`](/docs/messages/blocking-prerender-viewport-runtime). The metadata equivalent is handled at [Uncached data in `generateMetadata()`](/docs/messages/blocking-prerender-metadata-dynamic). For errors in the page body rather than viewport, see [Next.js encountered uncached data during prerendering](/docs/messages/blocking-prerender-dynamic).
> **Good to know**: In [`next dev`](/docs/app/api-reference/cli/next#next-dev-options), the error overlay points at the failing component. Run `next build --debug-prerender` to get the full list of blocking routes with stack traces. When iterating on specific routes, use `next build --debug-build-paths /dashboard /settings` to rebuild only those pages.
## Ways to fix this
<FixOption
group="cache"
href="#cache-the-viewport-data"
prompt={`Add "use cache" as the first statement inside generateViewport(). This caches the viewport so Next.js can include it in the prerender. Optionally call cacheLife(profile) to set automatic expiration. Do not introduce new imports beyond "next/cache".`}
title="Cache the viewport data"
>
Cache the viewport function so the result is reused and the route stays
prerenderable.
</FixOption>
<FixOption
group="block"
href="#allow-blocking-route"
prompt={`Add "export const unstable_instant = false" as a top-level export in the page or layout file. This silences the warning for this segment. Confirm with the user that the route is intentionally fully dynamic before applying this change: the export exempts the segment from instant-navigation validation, and the route renders on every request.`}
title="Allow blocking route"
>
Opt this segment out of instant navigation. The route renders on every request
and every navigation blocks.
</FixOption>
## Cache the viewport data
Choose this fix when the viewport values come from an external source (database, CMS) but don't need to change on every request. Add the [`use cache`](/docs/app/api-reference/directives/use-cache) directive as the first statement inside [`generateViewport()`](/docs/app/api-reference/functions/generate-viewport). Next.js caches the returned viewport object and includes it in the prerender.
### Patterns
#### Add `use cache` to `generateViewport`
Mark the function as cacheable. The viewport is evaluated once per cache window and reused.
```jsx filename="app/layout.js"
import { db } from './db'
export async function generateViewport() {
'use cache'
const { width, initialScale } = await db.query('viewport-config')
return { width, initialScale }
}
export default function RootLayout({ children }) {
return (
<html>
<body>{children}</body>
</html>
)
}
```
Learn more: [Caching with `use cache`](/docs/app/api-reference/directives/use-cache).
### Trade-off
Freshness depends on the cache configuration. The viewport stays the same until [`cacheLife`](/docs/app/api-reference/functions/cacheLife) expires or [`cacheTag`](/docs/app/api-reference/functions/cacheTag) is invalidated.
### Gotchas
- Inside a [`use cache`](/docs/app/api-reference/directives/use-cache) scope, you can't call [`cookies()`](/docs/app/api-reference/functions/cookies) or [`headers()`](/docs/app/api-reference/functions/headers). If the viewport needs a request-bound value (a theme color from a cookie), use [Allow blocking route](#allow-blocking-route) instead.
- A short [`cacheLife`](/docs/app/api-reference/functions/cacheLife) (a profile whose `revalidate` is shorter than the prerender's effective lifetime) prevents the viewport from being included in the prerender. Use a longer profile if you want the viewport included in the static shell.
## Allow blocking route
Choose this fix when the viewport data is genuinely uncacheable. Setting [`unstable_instant`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to `false` exempts the segment from instant-navigation validation. The page renders on every request and the navigation blocks until that render completes.
Unlike page body content, viewport metadata can't be deferred behind [`<Suspense>`](https://react.dev/reference/react/Suspense) because it affects the initial HTML `<head>`. Making the viewport dynamic means the entire page navigation blocks.
### Patterns
#### Opt the layout out
Set [`unstable_instant`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to `false` on the layout that defines `generateViewport`. The layout and every route in its subtree are exempted from instant-navigation validation. Apply this to the nested layout that owns the dynamic viewport, not the root layout, so the opt-out is scoped to the affected subtree.
```jsx filename="app/dashboard/layout.js"
import { db } from './db'
export const unstable_instant = false
export async function generateViewport() {
const { width, initialScale } = await db.query('viewport-config')
return { width, initialScale }
}
export default function DashboardLayout({ children }) {
return children
}
```
Learn more: [Route segment `instant` config](/docs/app/api-reference/file-conventions/route-segment-config/instant).
Use this pattern when:
- The viewport data is uncacheable and must be fetched on every request.
- You're migrating a route incrementally and want to defer the lifetime decision without changing how the page renders today.
Don't use this to dismiss the error. Choose [Cache the viewport data](#cache-the-viewport-data) when feasible.
### Trade-off
Navigations to this route are not instant. The user waits for the full server render before any HTML arrives. Use this only when that latency is necessary for the route to function.
### Gotchas
- Setting [`unstable_instant`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to `false` on a layout exempts every route in the subtree, not only the layout itself. Audit child routes before opting a shared layout out.
- This export does not disable [prerendering](/docs/app/glossary#prerendering). The route still prerenders if it can. It only silences the instant-navigation validation error.
- Framework-synthesized routes (`/_not-found`, `/_global-error`) inherit the root layout's `generateViewport` and must be statically prerendered. [`unstable_instant = false`](/docs/app/api-reference/file-conventions/route-segment-config/instant) silences the validation error but does not let those routes through, so the build still fails when they prerender. If your root layout's `generateViewport` depends on request data, [Cache the viewport data](#cache-the-viewport-data) instead, or move to [`global-not-found.js`](/docs/app/api-reference/file-conventions/not-found#global-not-foundjs-experimental), which bypasses the root layout entirely and avoids inheriting its `generateViewport`.
## Don't want this validation?
Instant-navigation validation runs by default in [Cache Components](/docs/app/api-reference/config/next-config-js/cacheComponents) apps and is what surfaces this error.
- **One segment**: add [`export const unstable_instant = false`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to the page or layout file. This opts out the segment itself. Child segments are still validated during client navigations.
- **Layout and its children**: add `export const unstable_instant = { unstable_disableValidation: true }` to a layout. This disables validation for that layout and every segment below it.
- **Entire app**: set [`experimental.instantInsights.validationLevel`](/docs/app/api-reference/file-conventions/route-segment-config/instant#configuring-validation-defaults) to `'manual-warning'` in `next.config`. This limits validation to segments that explicitly export `unstable_instant`.
See [Ensuring instant navigations](/docs/app/guides/instant-navigation) for the full model.
## Useful links
- [Ensuring instant navigations](/docs/app/guides/instant-navigation)
- [Runtime data in `generateViewport()`](/docs/messages/blocking-prerender-viewport-runtime)
- [Uncached data in `generateMetadata()`](/docs/messages/blocking-prerender-metadata-dynamic)
---
title: Next.js encountered runtime data in generateViewport()
kind: insight
---
During [prerendering](/docs/app/glossary#prerendering), [`generateViewport()`](/docs/app/api-reference/functions/generate-viewport) read a per-request value ([`cookies()`](/docs/app/api-reference/functions/cookies), [`headers()`](/docs/app/api-reference/functions/headers), [`params`](/docs/app/api-reference/file-conventions/page#params-optional), [`searchParams`](/docs/app/api-reference/file-conventions/page#searchparams-optional)). With [Cache Components](/docs/app/api-reference/config/next-config-js/cacheComponents) enabled, viewport metadata can't be deferred behind a [`<Suspense>`](https://react.dev/reference/react/Suspense) boundary because it affects the initial page load. The page can't be prerendered, so navigations block instead of being [instant](/docs/app/guides/instant-navigation).
Uncached data accesses ([`fetch()`](https://developer.mozilla.org/en-US/docs/Web/API/Window/fetch), database calls, [`await connection()`](/docs/app/api-reference/functions/connection)) in `generateViewport()` have different fixes. See [Next.js encountered uncached data in `generateViewport()`](/docs/messages/blocking-prerender-viewport-dynamic). The metadata equivalent is handled at [Runtime data in `generateMetadata()`](/docs/messages/blocking-prerender-metadata-runtime). For errors in the page body rather than viewport, see [Next.js encountered runtime data during prerendering](/docs/messages/blocking-prerender-runtime).
> **Good to know**: In [`next dev`](/docs/app/api-reference/cli/next#next-dev-options), the error overlay points at the failing component. Run `next build --debug-prerender` to get the full list of blocking routes with stack traces. When iterating on specific routes, use `next build --debug-build-paths /dashboard /settings` to rebuild only those pages.
## Ways to fix this
<FixOption
group="static"
href="#use-static-viewport"
prompt={`Replace the generateViewport() function with a static viewport export. Convert all dynamic values to static ones. Do not introduce new imports.`}
title="Use static viewport"
>
Replace the dynamic function with a static export so the viewport is known at
build time.
</FixOption>
<FixOption
group="block"
href="#allow-blocking-route"
prompt={`Add "export const unstable_instant = false" as a top-level export in the page or layout file. This silences the warning for this segment. Confirm with the user that the route is intentionally fully dynamic before applying this change: the export exempts the segment from instant-navigation validation, and the route renders on every request.`}
title="Allow blocking route"
>
Opt this segment out of instant navigation. The route renders on every request
and every navigation blocks.
</FixOption>
## Use static viewport
Choose this fix when the viewport doesn't actually need the per-request data, either because the values are known at build time, or because the dependency on runtime data is accidental and can be refactored away. Replace [`generateViewport()`](/docs/app/api-reference/functions/generate-viewport) with a static [`viewport`](/docs/app/api-reference/functions/generate-viewport#the-viewport-object) export, or rewrite `generateViewport()` so it no longer reads [`cookies()`](/docs/app/api-reference/functions/cookies), [`headers()`](/docs/app/api-reference/functions/headers), or other request-bound APIs. The values are evaluated once during the build.
### Patterns
#### Export a static object
Replace the function with a plain object export.
```jsx filename="app/layout.js"
export const viewport = {
themeColor: '#000000',
width: 'device-width',
initialScale: 1,
}
export default function RootLayout({ children }) {
return (
<html>
<body>{children}</body>
</html>
)
}
```
Learn more: [Static viewport](/docs/app/api-reference/functions/generate-viewport#the-viewport-object).
### Trade-off
Static viewport can't reflect per-request values like a user's preferred theme color stored in a cookie. If the viewport must be personalized, use [Allow blocking route](#allow-blocking-route).
### Gotchas
- The `viewport` export is typically set in the root layout. Changing a layout's viewport affects every route in its subtree.
- [`themeColor`](/docs/app/api-reference/functions/generate-viewport#themecolor) is the most common reason for a dynamic `generateViewport`. Consider whether a single static value covers all cases before resorting to a blocking route.
## Allow blocking route
Choose this fix when the viewport genuinely requires per-request data (a theme color from a cookie, a user-preferred width) and a static export isn't feasible. Setting [`unstable_instant`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to `false` exempts the segment from instant-navigation validation. The page renders on every request and the navigation blocks until that render completes.
Unlike page body content, viewport metadata can't be deferred behind [`<Suspense>`](https://react.dev/reference/react/Suspense) because it affects the initial HTML `<head>`. Making the viewport dynamic means the entire page navigation blocks.
### Patterns
#### Opt the layout out
Set [`unstable_instant`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to `false` on the layout that defines `generateViewport`. The layout and every route in its subtree are exempted from instant-navigation validation. Apply this to the nested layout that owns the dynamic viewport, not the root layout, so the opt-out is scoped to the affected subtree.
```jsx filename="app/dashboard/layout.js"
import { cookies } from 'next/headers'
export const unstable_instant = false
export async function generateViewport() {
const cookieJar = await cookies()
return {
themeColor: cookieJar.get('theme-color')?.value ?? '#000',
}
}
export default function DashboardLayout({ children }) {
return children
}
```
Learn more: [Route segment `instant` config](/docs/app/api-reference/file-conventions/route-segment-config/instant).
Use this pattern when:
- The viewport is personalized per user and the value must be correct on the first paint (no flash).
- You're migrating a route incrementally and want to defer the lifetime decision without changing how the page renders today.
Don't use this to dismiss the error. Choose [Use static viewport](#use-static-viewport) when feasible.
### Trade-off
Navigations to this route are not instant. The user waits for the full server render before any HTML arrives. Use this only when that latency is necessary for the route to function.
### Gotchas
- Setting [`unstable_instant`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to `false` on a layout exempts every route in the subtree, not only the layout itself. Audit child routes before opting a shared layout out.
- This export does not disable [prerendering](/docs/app/glossary#prerendering). The route still prerenders if it can. It only silences the instant-navigation validation error.
- If the dynamic viewport is the only reason the route blocks, consider whether a static default covers most users. A static `themeColor` with a client-side correction after hydration may give a better experience than blocking the entire navigation.
- Framework-synthesized routes (`/_not-found`, `/_global-error`) inherit the root layout's `generateViewport` and must be statically prerendered. [`unstable_instant = false`](/docs/app/api-reference/file-conventions/route-segment-config/instant) silences the validation error but does not let those routes through, so the build still fails when they prerender. If your root layout's `generateViewport` depends on request data, [Use static viewport](#use-static-viewport) instead, or move to [`global-not-found.js`](/docs/app/api-reference/file-conventions/not-found#global-not-foundjs-experimental), which bypasses the root layout entirely and avoids inheriting its `generateViewport`.
## Don't want this validation?
Instant-navigation validation runs by default in [Cache Components](/docs/app/api-reference/config/next-config-js/cacheComponents) apps and is what surfaces this error.
- **One segment**: add [`export const unstable_instant = false`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to the page or layout file. This opts out the segment itself. Child segments are still validated during client navigations.
- **Layout and its children**: add `export const unstable_instant = { unstable_disableValidation: true }` to a layout. This disables validation for that layout and every segment below it.
- **Entire app**: set [`experimental.instantInsights.validationLevel`](/docs/app/api-reference/file-conventions/route-segment-config/instant#configuring-validation-defaults) to `'manual-warning'` in `next.config`. This limits validation to segments that explicitly export `unstable_instant`.
See [Ensuring instant navigations](/docs/app/guides/instant-navigation) for the full model.
## Useful links
- [Ensuring instant navigations](/docs/app/guides/instant-navigation)
- [Uncached data in `generateViewport()`](/docs/messages/blocking-prerender-viewport-dynamic)
- [Runtime data in `generateMetadata()`](/docs/messages/blocking-prerender-metadata-runtime)
---
title: Next.js could not validate that a segment in your UI has instant navigation
kind: insight
---
During [prerendering](/docs/app/glossary#prerendering), a segment in the route tree was dropped from rendering. With [Cache Components](/docs/app/api-reference/config/next-config-js/cacheComponents) enabled, Next.js validates that every segment can produce an [instant navigation](/docs/app/guides/instant-navigation). When a segment is not rendered, that validation can't run and issues that would prevent instant navigation go undetected.
This typically happens when a layout conditionally omits `{children}`, a parallel route slot is not rendered, or a Client Component opts out of rendering during SSR.
> **Good to know**: In [`next dev`](/docs/app/api-reference/cli/next#next-dev-options), the error overlay points at the failing component. Run `next build --debug-prerender` to get the full list of blocking routes with stack traces. When iterating on specific routes, use `next build --debug-build-paths /dashboard /settings` to rebuild only those pages.
## Ways to fix this
<FixOption
group="render"
href="#render-the-dropped-segment"
prompt={`Ensure the layout renders {children} so the dropped segment is included in the render tree. If the layout conditionally omits {children} (e.g. showing a login page instead), restructure so both branches render {children} and use a Suspense boundary or conditional content inside the child segment instead. If the segment is a parallel route slot, ensure the layout renders the slot prop.`}
title="Render the dropped segment"
>
Include the segment in the render tree so Next.js can validate it for instant
navigation.
</FixOption>
<FixOption
group="ignore"
href="#skip-validation-on-the-segment"
prompt={`Add "export const unstable_instant = false" as a top-level export in the dropped segment's page or layout file. This silences the warning for the dropped segment and tells Next.js the segment does not need instant-navigation validation. Confirm with the user that skipping validation is intentional before applying this change.`}
title="Skip validation on the segment"
>
Opt the dropped segment out of instant-navigation validation.
</FixOption>
## Render the dropped segment
Choose this fix when the segment should be part of the render tree. The layout that owns the segment needs to render `{children}` (or the parallel route slot prop) so Next.js can validate the subtree for instant navigation.
### Patterns
#### Render `{children}` in the layout
Make sure the layout always includes `{children}` in its output. If the layout conditionally shows different content (a login page when unauthenticated, a dashboard when authenticated), render `{children}` in both branches and handle the conditional inside the child segment.
```jsx filename="app/dashboard/layout.js"
export default function DashboardLayout({ children }) {
return (
<>
<Nav />
{children}
</>
)
}
```
#### Render the parallel route slot
When the dropped segment is a parallel route (e.g. `@modal`), the layout must render the slot prop. If the slot should be hidden in certain states, render it conditionally inside the slot's own page rather than omitting the prop from the layout.
```jsx filename="app/dashboard/layout.js"
export default function DashboardLayout({ children, modal }) {
return (
<>
{children}
{modal}
</>
)
}
```
Learn more: [Parallel Routes](/docs/app/api-reference/file-conventions/parallel-routes).
#### Move auth or guard checks into the page
A common cause is a layout that conditionally returns a sign-in screen (or redirects) instead of rendering `{children}`. Layouts and pages render separately, so put the guard at the page (or slot) level rather than in the layout. The layout always renders `{children}`; each page decides whether to render its content or redirect.
```jsx filename="app/dashboard/layout.js"
export default function DashboardLayout({ children }) {
return (
<>
<Nav />
{children}
</>
)
}
```
```jsx filename="app/dashboard/page.js"
import { redirect } from 'next/navigation'
import { getSession } from '@/lib/session'
export default async function DashboardPage() {
const session = await getSession()
if (!session) redirect('/login')
return <Dashboard session={session} />
}
```
Learn more: [Authentication](/docs/app/guides/authentication).
### Trade-off
The segment is always in the render tree, which means Next.js validates it on every dev render. If the segment has dynamic data, it needs its own [`<Suspense>`](https://react.dev/reference/react/Suspense) boundary or caching strategy to stay prerenderable.
### Gotchas
- A layout that conditionally returns early without rendering `{children}` (e.g. a redirect guard) drops every segment in the subtree. Move the guard into a wrapper component inside `{children}` instead.
- A Client Component that returns `null` during SSR also drops its children from the render tree, triggering this error. Use a [`<Suspense>`](https://react.dev/reference/react/Suspense) boundary above the Client Component so the fallback renders in place of the skipped subtree.
## Skip validation on the segment
Choose this fix when the segment is intentionally not rendered in certain states (a modal that only appears on interaction, a slot gated by authentication). Setting [`unstable_instant`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to `false` on the dropped segment tells Next.js to skip validation for it.
### Patterns
#### Opt the dropped segment out
Add the export to the page or layout file of the segment that was dropped from rendering.
```jsx filename="app/dashboard/@modal/page.js"
export const unstable_instant = false
export default function ModalPage() {
return <Modal />
}
```
Learn more: [Route segment `instant` config](/docs/app/api-reference/file-conventions/route-segment-config/instant).
### Trade-off
The segment is exempt from instant-navigation validation. If it has issues that would block navigation (uncached data outside Suspense, runtime APIs), those issues won't be caught during development.
### Gotchas
- The export must be on the **dropped segment's own file** (page or layout), not on a parent. The framework walks top-down and the first explicit config wins.
- Setting [`unstable_instant`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to `false` does not disable [prerendering](/docs/app/glossary#prerendering). The segment still prerenders if it can. It only silences the validation error.
## Don't want this validation?
Instant-navigation validation runs by default in [Cache Components](/docs/app/api-reference/config/next-config-js/cacheComponents) apps and is what surfaces this error.
- **One segment**: add [`export const unstable_instant = false`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to the page or layout file. This opts out the segment itself. Child segments are still validated during client navigations.
- **Layout and its children**: add `export const unstable_instant = { unstable_disableValidation: true }` to a layout. This disables validation for that layout and every segment below it.
- **Entire app**: set [`experimental.instantInsights.validationLevel`](/docs/app/api-reference/file-conventions/route-segment-config/instant#configuring-validation-defaults) to `'manual-warning'` in `next.config`. This limits validation to segments that explicitly export `unstable_instant`.
See [Ensuring instant navigations](/docs/app/guides/instant-navigation) for the full model.
## Useful links
- [Parallel Routes](/docs/app/api-reference/file-conventions/parallel-routes)
- [Ensuring instant navigations](/docs/app/guides/instant-navigation)
- [Route segment `instant` config](/docs/app/api-reference/file-conventions/route-segment-config/instant)
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