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

docs: add ensureStatic reference and validation guidance (#99355)

## Summary

- document the `ensureStatic` route segment config for Next.js 16.4,
including the `shell`, `prefetch`, and `navigation` levels, their
prerequisites, and how requirements compose across pages, layouts, and
parallel routes
- add the validation experience for `ensureStatic = 'navigation'`,
including direct Learn more links, route, metadata, and viewport
guidance, cause-oriented fix cards, and build diagnostics
- add focused coverage for route content, metadata, viewport, cache
lifetimes, server promises, and dynamic parameters

This PR documents the final public `ensureStatic` name. The framework
export change lands separately.

Short-lived cache failures use the normal runtime-data or uncached-data
message selected by the existing validator. They do not have a separate
cache-lifetime classifier.

## Design and capture review

- Route: [runtime
data](https://error-messages-overhaul-ibsl.labs.vercel.dev/scenario/125-ensure-static-cookies),
[uncached
data](https://error-messages-overhaul-ibsl.labs.vercel.dev/scenario/128-ensure-static-uncached),
[connection](https://error-messages-overhaul-ibsl.labs.vercel.dev/scenario/129-ensure-static-connection)
- Metadata: [runtime
data](https://error-messages-overhaul-ibsl.labs.vercel.dev/scenario/130-ensure-static-metadata-runtime),
[uncached
data](https://error-messages-overhaul-ibsl.labs.vercel.dev/scenario/131-ensure-static-metadata-dynamic)
- Viewport: [runtime
data](https://error-messages-overhaul-ibsl.labs.vercel.dev/scenario/132-ensure-static-viewport-runtime),
[uncached
data](https://error-messages-overhaul-ibsl.labs.vercel.dev/scenario/133-ensure-static-viewport-dynamic)
- Cache lifetimes: [short
expire](https://error-messages-overhaul-ibsl.labs.vercel.dev/scenario/134-ensure-static-short-expire),
[short
stale](https://error-messages-overhaul-ibsl.labs.vercel.dev/scenario/135-ensure-static-short-stale),
[`revalidate:
0`](https://error-messages-overhaul-ibsl.labs.vercel.dev/scenario/136-ensure-static-zero-revalidate)
- Other validation: [`instant =
false`](https://error-messages-overhaul-ibsl.labs.vercel.dev/scenario/137-ensure-static-instant-false),
[Suspense](https://error-messages-overhaul-ibsl.labs.vercel.dev/scenario/138-ensure-static-suspense),
[server
promise](https://error-messages-overhaul-ibsl.labs.vercel.dev/scenario/139-ensure-static-client-promise),
[missing
parameters](https://error-messages-overhaul-ibsl.labs.vercel.dev/scenario/144-ensure-static-missing-params)

## Verification

- `pnpm --filter=next build`
- Development E2E: 27 tests and 19 snapshots passed
- Production E2E: 27 tests and 20 snapshots passed
- Focused overlay message and fix-card unit suites: 137 tests passed
- Error-overhaul production build: 124 routes generated
- Captured build output for 22 Ensure Static scenarios and dev overlays
for all applicable insight cases
- Prettier, ESLint, and `git diff --check` passed for the changed
framework files
- Documentation link validation passed

<!-- NEXT_JS_LLM -->

---------
Co-authored-by: 's avatarJoseph Chamochumbi <joseph.chamochumbi@vercel.com>
parent e4ceb139
......@@ -12,6 +12,12 @@ The Route Segment Config options allow you to configure the behavior of a [Page]
| [`preferredRegion`](/docs/app/api-reference/file-conventions/route-segment-config/preferredRegion) | `'auto' \| 'global' \| 'home' \| string \| string[] (deprecated)` | `'auto'` |
| [`maxDuration`](/docs/app/api-reference/file-conventions/route-segment-config/maxDuration) | `number` | Set by deployment platform |
With [Cache Components](/docs/app/api-reference/config/next-config-js/cacheComponents) enabled, pages and layouts also support the following option:
| Option | Type | Default |
| -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | -------- |
| [`ensureStatic`](/docs/app/api-reference/file-conventions/route-segment-config/ensureStatic) | `'auto'` \| `'shell'` \| `'prefetch'` \| `'navigation'` \| `false` | `'auto'` |
## Version History
| Version | |
......
......@@ -54,6 +54,7 @@ export default async function Page({ params }) {
> **Good to know**:
>
> - You can use the [`dynamicParams`](/docs/app/api-reference/file-conventions/route-segment-config/dynamicParams) segment config option to control what happens when a dynamic segment is visited that was not generated with `generateStaticParams`.
> - A dynamic route that uses [`ensureStatic = 'navigation'`](/docs/app/api-reference/file-conventions/route-segment-config/ensureStatic#navigation) must return at least one params object, and every object must include all dynamic parameters for the route. See the [`generateStaticParams` error guide](/docs/messages/generate-static-params#with-ensurestatic).
> - You must return [an empty array from `generateStaticParams`](#all-paths-at-runtime) or utilize [`export const dynamic = 'force-static'`](/docs/app/guides/caching-without-cache-components#dynamic) in order to revalidate (ISR) [paths at runtime](#all-paths-at-runtime).
> - During `next dev`, `generateStaticParams` will be called when you navigate to a route.
> - During `next build`, `generateStaticParams` runs before the corresponding Layouts or Pages are generated.
......
......@@ -144,6 +144,10 @@ See [Proxy](#proxy).
# N
## Navigation stages
The points at which server-rendered work becomes available during a client navigation. With [Partial Prefetching](#partial-prefetching), the stages are the [App Shell](#app-shell), a per-link prefetch, and the navigation. Learn more in the [`ensureStatic`](/docs/app/api-reference/file-conventions/route-segment-config/ensureStatic), [`prefetch()`](/docs/app/api-reference/functions/prefetch), and [`navigation()`](/docs/app/api-reference/functions/navigation) API references.
## Not Found
A special component shown when a route doesn't exist or when the [`notFound()` function](/docs/app/api-reference/functions/not-found) is called. Created by adding a [`not-found.js` file](/docs/app/api-reference/file-conventions/not-found) to your app directory. Learn more in [Error Handling](/docs/app/getting-started/error-handling#not-found).
......
---
title: Next.js encountered URL data in a Client Component outside of Suspense
kind: insight
kind: error
---
<div
......@@ -14,7 +14,7 @@ kind: insight
lineHeight: '1.6',
}}
>
This Insight is part of the [Instant
This error is part of the [Instant
Navigations](https://nextjs.org/blog/next-16-3-instant-navigations) feature
introduced in Next.js 16.3. If you're new to it, start with the [Ensuring
instant navigations](/docs/app/guides/instant-navigation) guide for an
......@@ -70,7 +70,7 @@ export default function Page() {
return (
<main>
<h1>Dashboard</h1>
<Suspense fallback={<p>Loading search...</p>}>
<Suspense fallback={<p>Loading search…</p>}>
<Search />
</Suspense>
</main>
......@@ -268,20 +268,6 @@ Instant-navigation validation runs by default in [Cache Components](/docs/app/ap
See [Ensuring instant navigations](/docs/app/guides/instant-navigation) for the full model.
## Related Insights
- [Runtime data during prerendering](/docs/messages/blocking-prerender-runtime)
- [Uncached data during prerendering](/docs/messages/blocking-prerender-dynamic)
- [Runtime data in `generateMetadata()`](/docs/messages/blocking-prerender-metadata-runtime)
- [Uncached data in `generateMetadata()`](/docs/messages/blocking-prerender-metadata-dynamic)
- [Runtime data in `generateViewport()`](/docs/messages/blocking-prerender-viewport-runtime)
- [Uncached data in `generateViewport()`](/docs/messages/blocking-prerender-viewport-dynamic)
- [`Math.random()` while prerendering](/docs/messages/blocking-prerender-random)
- [`Math.random()` in a Client Component](/docs/messages/blocking-prerender-random-client)
- [`Date.now()` while prerendering](/docs/messages/blocking-prerender-current-time)
- [`Date.now()` in a Client Component](/docs/messages/blocking-prerender-current-time-client)
- [Crypto APIs while prerendering](/docs/messages/blocking-prerender-crypto)
- [Crypto APIs in a Client Component](/docs/messages/blocking-prerender-crypto-client)
- [Dynamic data during prefetching](/docs/messages/instant-link-prefetch-partial)
- [URL data outside of Suspense](/docs/messages/instant-shell-url-data)
- [Unrendered segment](/docs/messages/instant-unrendered-segment)
## Related validation errors
See [Instant Navigation validation errors](/docs/messages/instant-navigation-validation) for the complete reference.
---
title: Next.js encountered the unstable value crypto.randomUUID() in a Client Component
kind: insight
kind: error
---
<div
......@@ -14,7 +14,7 @@ kind: insight
lineHeight: '1.6',
}}
>
This Insight is part of the [Instant
This error is part of the [Instant
Navigations](https://nextjs.org/blog/next-16-3-instant-navigations) feature
introduced in Next.js 16.3. If you're new to it, start with the [Ensuring
instant navigations](/docs/app/guides/instant-navigation) guide for an
......@@ -240,20 +240,6 @@ In [`next dev`](/docs/app/api-reference/cli/next#next-dev-options), the error ov
This error fires from the prerender, not from instant-navigation validation. `crypto.randomUUID()` and related APIs return a different value on every call, so the prerender can't bake them into a static shell regardless of the segment's `instant` config or [`experimental.instantInsights.validationLevel`](/docs/app/api-reference/file-conventions/route-segment-config/instant#configuring-validation-defaults). Use one of the fixes above.
## Related Insights
- [Runtime data during prerendering](/docs/messages/blocking-prerender-runtime)
- [Uncached data during prerendering](/docs/messages/blocking-prerender-dynamic)
- [URL data in a Client Component outside of Suspense](/docs/messages/blocking-prerender-client-hook)
- [Runtime data in `generateMetadata()`](/docs/messages/blocking-prerender-metadata-runtime)
- [Uncached data in `generateMetadata()`](/docs/messages/blocking-prerender-metadata-dynamic)
- [Runtime data in `generateViewport()`](/docs/messages/blocking-prerender-viewport-runtime)
- [Uncached data in `generateViewport()`](/docs/messages/blocking-prerender-viewport-dynamic)
- [`Math.random()` while prerendering](/docs/messages/blocking-prerender-random)
- [`Math.random()` in a Client Component](/docs/messages/blocking-prerender-random-client)
- [`Date.now()` while prerendering](/docs/messages/blocking-prerender-current-time)
- [`Date.now()` in a Client Component](/docs/messages/blocking-prerender-current-time-client)
- [Crypto APIs while prerendering](/docs/messages/blocking-prerender-crypto)
- [Dynamic data during prefetching](/docs/messages/instant-link-prefetch-partial)
- [URL data outside of Suspense](/docs/messages/instant-shell-url-data)
- [Unrendered segment](/docs/messages/instant-unrendered-segment)
## Related validation errors
See [Instant Navigation validation errors](/docs/messages/instant-navigation-validation) for the complete reference.
---
title: Next.js encountered the unstable value crypto.randomUUID() while prerendering
kind: insight
kind: error
---
<div
......@@ -14,7 +14,7 @@ kind: insight
lineHeight: '1.6',
}}
>
This Insight is part of the [Instant
This error is part of the [Instant
Navigations](https://nextjs.org/blog/next-16-3-instant-navigations) feature
introduced in Next.js 16.3. If you're new to it, start with the [Ensuring
instant navigations](/docs/app/guides/instant-navigation) guide for an
......@@ -256,20 +256,6 @@ In [`next dev`](/docs/app/api-reference/cli/next#next-dev-options), the error ov
This error fires from the prerender, not from instant-navigation validation. `crypto.randomUUID()` and related APIs return a different value on every call, so the prerender can't bake them into a static shell regardless of the segment's `instant` config or [`experimental.instantInsights.validationLevel`](/docs/app/api-reference/file-conventions/route-segment-config/instant#configuring-validation-defaults). Use one of the fixes above.
## Related Insights
- [Runtime data during prerendering](/docs/messages/blocking-prerender-runtime)
- [Uncached data during prerendering](/docs/messages/blocking-prerender-dynamic)
- [URL data in a Client Component outside of Suspense](/docs/messages/blocking-prerender-client-hook)
- [Runtime data in `generateMetadata()`](/docs/messages/blocking-prerender-metadata-runtime)
- [Uncached data in `generateMetadata()`](/docs/messages/blocking-prerender-metadata-dynamic)
- [Runtime data in `generateViewport()`](/docs/messages/blocking-prerender-viewport-runtime)
- [Uncached data in `generateViewport()`](/docs/messages/blocking-prerender-viewport-dynamic)
- [`Math.random()` while prerendering](/docs/messages/blocking-prerender-random)
- [`Math.random()` in a Client Component](/docs/messages/blocking-prerender-random-client)
- [`Date.now()` while prerendering](/docs/messages/blocking-prerender-current-time)
- [`Date.now()` in a Client Component](/docs/messages/blocking-prerender-current-time-client)
- [Crypto APIs in a Client Component](/docs/messages/blocking-prerender-crypto-client)
- [Dynamic data during prefetching](/docs/messages/instant-link-prefetch-partial)
- [URL data outside of Suspense](/docs/messages/instant-shell-url-data)
- [Unrendered segment](/docs/messages/instant-unrendered-segment)
## Related validation errors
See [Instant Navigation validation errors](/docs/messages/instant-navigation-validation) for the complete reference.
---
title: Next.js encountered the unstable value Date.now() in a Client Component
kind: insight
kind: error
---
<div
......@@ -14,7 +14,7 @@ kind: insight
lineHeight: '1.6',
}}
>
This Insight is part of the [Instant
This error is part of the [Instant
Navigations](https://nextjs.org/blog/next-16-3-instant-navigations) feature
introduced in Next.js 16.3. If you're new to it, start with the [Ensuring
instant navigations](/docs/app/guides/instant-navigation) guide for an
......@@ -284,20 +284,6 @@ In [`next dev`](/docs/app/api-reference/cli/next#next-dev-options), the error ov
This error fires from the prerender, not from instant-navigation validation. `new Date()` and `Date.now()` return a different value on every render, so the prerender can't bake them into a static shell regardless of the segment's `instant` config or [`experimental.instantInsights.validationLevel`](/docs/app/api-reference/file-conventions/route-segment-config/instant#configuring-validation-defaults). Use one of the fixes above.
## Related Insights
- [Runtime data during prerendering](/docs/messages/blocking-prerender-runtime)
- [Uncached data during prerendering](/docs/messages/blocking-prerender-dynamic)
- [URL data in a Client Component outside of Suspense](/docs/messages/blocking-prerender-client-hook)
- [Runtime data in `generateMetadata()`](/docs/messages/blocking-prerender-metadata-runtime)
- [Uncached data in `generateMetadata()`](/docs/messages/blocking-prerender-metadata-dynamic)
- [Runtime data in `generateViewport()`](/docs/messages/blocking-prerender-viewport-runtime)
- [Uncached data in `generateViewport()`](/docs/messages/blocking-prerender-viewport-dynamic)
- [`Math.random()` while prerendering](/docs/messages/blocking-prerender-random)
- [`Math.random()` in a Client Component](/docs/messages/blocking-prerender-random-client)
- [`Date.now()` while prerendering](/docs/messages/blocking-prerender-current-time)
- [Crypto APIs while prerendering](/docs/messages/blocking-prerender-crypto)
- [Crypto APIs in a Client Component](/docs/messages/blocking-prerender-crypto-client)
- [Dynamic data during prefetching](/docs/messages/instant-link-prefetch-partial)
- [URL data outside of Suspense](/docs/messages/instant-shell-url-data)
- [Unrendered segment](/docs/messages/instant-unrendered-segment)
## Related validation errors
See [Instant Navigation validation errors](/docs/messages/instant-navigation-validation) for the complete reference.
---
title: Next.js encountered the unstable value Date.now() while prerendering
kind: insight
kind: error
---
<div
......@@ -14,7 +14,7 @@ kind: insight
lineHeight: '1.6',
}}
>
This Insight is part of the [Instant
This error is part of the [Instant
Navigations](https://nextjs.org/blog/next-16-3-instant-navigations) feature
introduced in Next.js 16.3. If you're new to it, start with the [Ensuring
instant navigations](/docs/app/guides/instant-navigation) guide for an
......@@ -313,20 +313,6 @@ In [`next dev`](/docs/app/api-reference/cli/next#next-dev-options), the error ov
This error fires from the prerender, not from instant-navigation validation. `new Date()` and `Date.now()` return a different value on every render, so the prerender can't bake them into a static shell regardless of the segment's `instant` config or [`experimental.instantInsights.validationLevel`](/docs/app/api-reference/file-conventions/route-segment-config/instant#configuring-validation-defaults). Use one of the fixes above.
## Related Insights
- [Runtime data during prerendering](/docs/messages/blocking-prerender-runtime)
- [Uncached data during prerendering](/docs/messages/blocking-prerender-dynamic)
- [URL data in a Client Component outside of Suspense](/docs/messages/blocking-prerender-client-hook)
- [Runtime data in `generateMetadata()`](/docs/messages/blocking-prerender-metadata-runtime)
- [Uncached data in `generateMetadata()`](/docs/messages/blocking-prerender-metadata-dynamic)
- [Runtime data in `generateViewport()`](/docs/messages/blocking-prerender-viewport-runtime)
- [Uncached data in `generateViewport()`](/docs/messages/blocking-prerender-viewport-dynamic)
- [`Math.random()` while prerendering](/docs/messages/blocking-prerender-random)
- [`Math.random()` in a Client Component](/docs/messages/blocking-prerender-random-client)
- [`Date.now()` in a Client Component](/docs/messages/blocking-prerender-current-time-client)
- [Crypto APIs while prerendering](/docs/messages/blocking-prerender-crypto)
- [Crypto APIs in a Client Component](/docs/messages/blocking-prerender-crypto-client)
- [Dynamic data during prefetching](/docs/messages/instant-link-prefetch-partial)
- [URL data outside of Suspense](/docs/messages/instant-shell-url-data)
- [Unrendered segment](/docs/messages/instant-unrendered-segment)
## Related validation errors
See [Instant Navigation validation errors](/docs/messages/instant-navigation-validation) for the complete reference.
---
title: Next.js encountered uncached data during prerendering or a navigation
kind: insight
kind: error
---
<div
......@@ -14,7 +14,7 @@ kind: insight
lineHeight: '1.6',
}}
>
This Insight is part of the [Instant
This error is part of the [Instant
Navigations](https://nextjs.org/blog/next-16-3-instant-navigations) feature
introduced in Next.js 16.3. If you're new to it, start with the [Ensuring
instant navigations](/docs/app/guides/instant-navigation) guide for an
......@@ -24,9 +24,11 @@ kind: insight
During [prerendering](/docs/app/glossary#prerendering), a [`fetch()`](https://developer.mozilla.org/en-US/docs/Web/API/Window/fetch) request, database call, [`await connection()`](/docs/app/api-reference/functions/connection), or other asynchronous IO ran outside of [`<Suspense>`](https://react.dev/reference/react/Suspense). With [Cache Components](/docs/app/api-reference/config/next-config-js/cacheComponents) enabled, Next.js can't prerender the part of the tree that depends on this data, so navigations to this route block instead of being [instant](/docs/app/guides/instant-navigation).
During `next build`, Next.js may link to this page when it cannot distinguish uncached data from runtime data. For a short cache, [extend the cache lifetime](/docs/messages/blocking-prerender-runtime#extend-the-cache-lifetime) or move the cached work inside `<Suspense>`.
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)) have different fixes. See [Next.js encountered runtime data during prerendering](/docs/messages/blocking-prerender-runtime).
This error can also appear during a client-side navigation when the data access sits inside a [`<Suspense>`](https://react.dev/reference/react/Suspense) boundary from a parent layout but that boundary is too high. It wraps the entire segment instead of only the dynamic part, so the navigation still blocks. Push the boundary closer to the data access so the rest of the segment stays in the [static shell](/docs/app/glossary#static-shell). See [Choosing where to place the boundary](#choosing-where-to-place-the-boundary).
An ancestor [`<Suspense>`](https://react.dev/reference/react/Suspense) boundary can allow the initial route to prerender. During a later client navigation, however, uncached data without a closer boundary in the destination route delays the route update. Add a boundary near the data access so the navigation can show a fallback while the uncached content renders. See [Choosing where to place the boundary](#choosing-where-to-place-the-boundary).
## Ways to fix this
......@@ -263,15 +265,8 @@ Freshness becomes a property of the cache configuration, not the data source. Th
- Variables captured from the surrounding scope are automatically bound as part of the cache key. That keeps cached entries per-value, but it also means a wide closure can balloon the key surface. Prefer passing the dependencies you care about as function arguments so the contract is explicit.
- The `"use cache"` directive runs on the server. It can't wrap a function that uses runtime APIs such as [`cookies()`](/docs/app/api-reference/functions/cookies) or [`headers()`](/docs/app/api-reference/functions/headers). Read those outside the cached scope and pass the values as arguments, or use [`"use cache: private"`](/docs/app/api-reference/directives/use-cache-private).
- If you cache a function and still see this error, the `cacheLife` may be too short to prerender. See [Short-lived caches](#short-lived-caches).
- The default in-memory cache is per-server-instance. If the upstream call is expensive and you want a shared cache across instances, use [`"use cache: remote"`](/docs/app/api-reference/directives/use-cache-remote) instead. It trades a network roundtrip for a single cache shared by all servers.
### Short-lived caches
[`"use cache"`](/docs/app/api-reference/directives/use-cache) accepts a [`cacheLife`](/docs/app/api-reference/functions/cacheLife) profile. A short profile (such as `"seconds"` or `"minutes"`) whose `revalidate` is shorter than the prerender's effective lifetime prevents the value from being included in the prerender. The segment becomes a dynamic hole instead. The cache entry still helps the [Client Cache](/docs/app/glossary#client-cache) and protects upstream APIs, but the page falls back to streaming.
To keep the page prerendered, use a profile with a longer revalidate window such as `"default"` (15 minutes), `"hours"`, or `"days"`. If a short profile is intentional, treat the value as dynamic and use [Wrap in or move into Suspense](#wrap-in-or-move-into-suspense) instead.
## Allow blocking route
Choose this fix when the route renders per-request and there's no useful static shell. Setting [`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.
......@@ -338,20 +333,6 @@ Instant-navigation validation runs by default in [Cache Components](/docs/app/ap
See [Ensuring instant navigations](/docs/app/guides/instant-navigation) for the full model.
## Related Insights
- [Runtime data during prerendering](/docs/messages/blocking-prerender-runtime)
- [URL data in a Client Component outside of Suspense](/docs/messages/blocking-prerender-client-hook)
- [Runtime data in `generateMetadata()`](/docs/messages/blocking-prerender-metadata-runtime)
- [Uncached data in `generateMetadata()`](/docs/messages/blocking-prerender-metadata-dynamic)
- [Runtime data in `generateViewport()`](/docs/messages/blocking-prerender-viewport-runtime)
- [Uncached data in `generateViewport()`](/docs/messages/blocking-prerender-viewport-dynamic)
- [`Math.random()` while prerendering](/docs/messages/blocking-prerender-random)
- [`Math.random()` in a Client Component](/docs/messages/blocking-prerender-random-client)
- [`Date.now()` while prerendering](/docs/messages/blocking-prerender-current-time)
- [`Date.now()` in a Client Component](/docs/messages/blocking-prerender-current-time-client)
- [Crypto APIs while prerendering](/docs/messages/blocking-prerender-crypto)
- [Crypto APIs in a Client Component](/docs/messages/blocking-prerender-crypto-client)
- [Dynamic data during prefetching](/docs/messages/instant-link-prefetch-partial)
- [URL data outside of Suspense](/docs/messages/instant-shell-url-data)
- [Unrendered segment](/docs/messages/instant-unrendered-segment)
## Related validation errors
See [Instant Navigation validation errors](/docs/messages/instant-navigation-validation) for the complete reference.
---
title: Next.js encountered uncached data in generateMetadata()
kind: insight
kind: error
---
<div
......@@ -14,7 +14,7 @@ kind: insight
lineHeight: '1.6',
}}
>
This Insight is part of the [Instant
This error is part of the [Instant
Navigations](https://nextjs.org/blog/next-16-3-instant-navigations) feature
introduced in Next.js 16.3. If you're new to it, start with the [Ensuring
instant navigations](/docs/app/guides/instant-navigation) guide for an
......@@ -24,6 +24,8 @@ kind: insight
During [prerendering](/docs/app/glossary#prerendering), [`generateMetadata()`](/docs/app/api-reference/functions/generate-metadata) 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, Next.js expects metadata to be prerenderable when the rest of the route is. This route's metadata is blocked, but the rest of its content can be prerendered.
During `next build`, Next.js may link to this page when it cannot distinguish uncached data from runtime data. For a short cache, [extend the cache lifetime](/docs/messages/blocking-prerender-metadata-runtime#extend-the-cache-lifetime).
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 `generateMetadata()` have different fixes. See [Next.js encountered runtime data in `generateMetadata()`](/docs/messages/blocking-prerender-metadata-runtime).
The viewport equivalent is handled at [Uncached data in `generateViewport()`](/docs/messages/blocking-prerender-viewport-dynamic).
......@@ -118,7 +120,6 @@ Freshness depends on the cache configuration. The metadata stays the same until
- [`use cache`](/docs/app/api-reference/directives/use-cache) can't be combined with [`cookies()`](/docs/app/api-reference/functions/cookies) or [`headers()`](/docs/app/api-reference/functions/headers) in the same scope. Inside a cached function, you can't call request-bound APIs. If the metadata needs a request-bound value (a session token to call a protected API), read it outside the cached scope and pass it as an argument, or use [Mark the route as dynamic](#mark-the-route-as-dynamic) instead.
- If the metadata function reads `params`, the params become part of the cache key automatically. Each unique param set gets its own cached metadata entry.
- A short [`cacheLife`](/docs/app/api-reference/functions/cacheLife) (a profile whose `revalidate` is shorter than the prerender's effective lifetime) prevents the metadata from being included in the prerender. The route becomes partially dynamic. Use a longer profile if you want the metadata included in the static shell.
## Mark the route as dynamic
......@@ -187,20 +188,6 @@ Instant-navigation validation runs by default in [Cache Components](/docs/app/ap
See [Ensuring instant navigations](/docs/app/guides/instant-navigation) for the full model.
## Related Insights
- [Runtime data during prerendering](/docs/messages/blocking-prerender-runtime)
- [Uncached data during prerendering](/docs/messages/blocking-prerender-dynamic)
- [URL data in a Client Component outside of Suspense](/docs/messages/blocking-prerender-client-hook)
- [Runtime data in `generateMetadata()`](/docs/messages/blocking-prerender-metadata-runtime)
- [Runtime data in `generateViewport()`](/docs/messages/blocking-prerender-viewport-runtime)
- [Uncached data in `generateViewport()`](/docs/messages/blocking-prerender-viewport-dynamic)
- [`Math.random()` while prerendering](/docs/messages/blocking-prerender-random)
- [`Math.random()` in a Client Component](/docs/messages/blocking-prerender-random-client)
- [`Date.now()` while prerendering](/docs/messages/blocking-prerender-current-time)
- [`Date.now()` in a Client Component](/docs/messages/blocking-prerender-current-time-client)
- [Crypto APIs while prerendering](/docs/messages/blocking-prerender-crypto)
- [Crypto APIs in a Client Component](/docs/messages/blocking-prerender-crypto-client)
- [Dynamic data during prefetching](/docs/messages/instant-link-prefetch-partial)
- [URL data outside of Suspense](/docs/messages/instant-shell-url-data)
- [Unrendered segment](/docs/messages/instant-unrendered-segment)
## Related validation errors
See [Instant Navigation validation errors](/docs/messages/instant-navigation-validation) for the complete reference.
---
title: Next.js encountered runtime data in generateMetadata()
kind: insight
kind: error
---
<div
......@@ -14,7 +14,7 @@ kind: insight
lineHeight: '1.6',
}}
>
This Insight is part of the [Instant
This error is part of the [Instant
Navigations](https://nextjs.org/blog/next-16-3-instant-navigations) feature
introduced in Next.js 16.3. If you're new to it, start with the [Ensuring
instant navigations](/docs/app/guides/instant-navigation) guide for an
......@@ -24,6 +24,8 @@ kind: insight
During [prerendering](/docs/app/glossary#prerendering), [`generateMetadata()`](/docs/app/api-reference/functions/generate-metadata) or file-based metadata 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, Next.js expects metadata to be prerenderable when the rest of the route is. This route's metadata is blocked, but the rest of its content can be prerendered.
A [`use cache`](/docs/app/api-reference/directives/use-cache) scope is also treated as runtime data when its [`expire`](/docs/app/api-reference/functions/cacheLife#expire) is under five minutes, [`stale`](/docs/app/api-reference/functions/cacheLife#stale) is under 30 seconds, or [`revalidate`](/docs/app/api-reference/functions/cacheLife#revalidate) is `0`.
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 `generateMetadata()` have different fixes. See [Next.js encountered uncached data in `generateMetadata()`](/docs/messages/blocking-prerender-metadata-dynamic).
The viewport equivalent is handled at [Runtime data in `generateViewport()`](/docs/messages/blocking-prerender-viewport-runtime).
......@@ -56,7 +58,7 @@ For errors in the page body rather than metadata, see [Next.js encountered runti
## Use static metadata
Choose this fix when the metadata values are known at build time and don't change per request. Replace [`generateMetadata()`](/docs/app/api-reference/functions/generate-metadata) with a static [`metadata`](/docs/app/api-reference/functions/generate-metadata#metadata-object) export. The metadata is evaluated once during the build and included in every prerender.
Choose this fix when the metadata values are known at build time and don't change per request. Replace [`generateMetadata()`](/docs/app/api-reference/functions/generate-metadata) with a static [`metadata`](/docs/app/api-reference/functions/generate-metadata#the-metadata-object) export. The metadata is evaluated once during the build and included in every prerender.
### Patterns
......@@ -75,7 +77,7 @@ export default function Page() {
}
```
Learn more: [Static metadata](/docs/app/api-reference/functions/generate-metadata#metadata-object).
Learn more: [Static metadata](/docs/app/api-reference/functions/generate-metadata#the-metadata-object).
#### Use `generateStaticParams` for per-param metadata
......@@ -161,6 +163,12 @@ The metadata and the dynamic marker run on every request, so the route cannot be
- If the page already has a genuinely dynamic component (one that reads [`cookies()`](/docs/app/api-reference/functions/cookies) or [`headers()`](/docs/app/api-reference/functions/headers) inside a [`<Suspense>`](https://react.dev/reference/react/Suspense) boundary), you won't see this error. The page is already partially dynamic.
- Framework-synthesized routes (`/_not-found`, `/_global-error`) inherit the root layout's `generateMetadata` and must be statically prerendered. The dynamic marker doesn't help here, because these routes don't have a page body where you can place a Suspense'd marker. If your root layout's `generateMetadata` depends on request data, [Use static metadata](#use-static-metadata) 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 `generateMetadata`.
## Other options
### Extend the cache lifetime
If a short cache triggered this error, set `expire` to at least five minutes, `stale` to at least 30 seconds, and `revalidate` above `0`. Increase the lifetime only when serving shared, older metadata is acceptable.
## Verifying the fix
After applying a fix, reload the route and confirm the page immediately paints meaningful UI, with any `<Suspense>` fallbacks covering only the regions that stream in. A [`<Suspense>`](https://react.dev/reference/react/Suspense) boundary placed around the whole page body can pass validation with an empty shell, which defeats the point of an instant navigation.
......@@ -176,20 +184,6 @@ Instant-navigation validation runs by default in [Cache Components](/docs/app/ap
See [Ensuring instant navigations](/docs/app/guides/instant-navigation) for the full model.
## Related Insights
- [Runtime data during prerendering](/docs/messages/blocking-prerender-runtime)
- [Uncached data during prerendering](/docs/messages/blocking-prerender-dynamic)
- [URL data in a Client Component outside of Suspense](/docs/messages/blocking-prerender-client-hook)
- [Uncached data in `generateMetadata()`](/docs/messages/blocking-prerender-metadata-dynamic)
- [Runtime data in `generateViewport()`](/docs/messages/blocking-prerender-viewport-runtime)
- [Uncached data in `generateViewport()`](/docs/messages/blocking-prerender-viewport-dynamic)
- [`Math.random()` while prerendering](/docs/messages/blocking-prerender-random)
- [`Math.random()` in a Client Component](/docs/messages/blocking-prerender-random-client)
- [`Date.now()` while prerendering](/docs/messages/blocking-prerender-current-time)
- [`Date.now()` in a Client Component](/docs/messages/blocking-prerender-current-time-client)
- [Crypto APIs while prerendering](/docs/messages/blocking-prerender-crypto)
- [Crypto APIs in a Client Component](/docs/messages/blocking-prerender-crypto-client)
- [Dynamic data during prefetching](/docs/messages/instant-link-prefetch-partial)
- [URL data outside of Suspense](/docs/messages/instant-shell-url-data)
- [Unrendered segment](/docs/messages/instant-unrendered-segment)
## Related validation errors
See [Instant Navigation validation errors](/docs/messages/instant-navigation-validation) for the complete reference.
---
title: Next.js encountered the unstable value Math.random() in a Client Component
kind: insight
kind: error
---
<div
......@@ -14,7 +14,7 @@ kind: insight
lineHeight: '1.6',
}}
>
This Insight is part of the [Instant
This error is part of the [Instant
Navigations](https://nextjs.org/blog/next-16-3-instant-navigations) feature
introduced in Next.js 16.3. If you're new to it, start with the [Ensuring
instant navigations](/docs/app/guides/instant-navigation) guide for an
......@@ -233,20 +233,6 @@ In [`next dev`](/docs/app/api-reference/cli/next#next-dev-options), the error ov
This error fires from the prerender, not from instant-navigation validation. `Math.random()` returns a different value on every render, so the prerender can't bake it into a static shell regardless of the segment's `instant` config or [`experimental.instantInsights.validationLevel`](/docs/app/api-reference/file-conventions/route-segment-config/instant#configuring-validation-defaults). Use one of the fixes above.
## Related Insights
- [Runtime data during prerendering](/docs/messages/blocking-prerender-runtime)
- [Uncached data during prerendering](/docs/messages/blocking-prerender-dynamic)
- [URL data in a Client Component outside of Suspense](/docs/messages/blocking-prerender-client-hook)
- [Runtime data in `generateMetadata()`](/docs/messages/blocking-prerender-metadata-runtime)
- [Uncached data in `generateMetadata()`](/docs/messages/blocking-prerender-metadata-dynamic)
- [Runtime data in `generateViewport()`](/docs/messages/blocking-prerender-viewport-runtime)
- [Uncached data in `generateViewport()`](/docs/messages/blocking-prerender-viewport-dynamic)
- [`Math.random()` while prerendering](/docs/messages/blocking-prerender-random)
- [`Date.now()` while prerendering](/docs/messages/blocking-prerender-current-time)
- [`Date.now()` in a Client Component](/docs/messages/blocking-prerender-current-time-client)
- [Crypto APIs while prerendering](/docs/messages/blocking-prerender-crypto)
- [Crypto APIs in a Client Component](/docs/messages/blocking-prerender-crypto-client)
- [Dynamic data during prefetching](/docs/messages/instant-link-prefetch-partial)
- [URL data outside of Suspense](/docs/messages/instant-shell-url-data)
- [Unrendered segment](/docs/messages/instant-unrendered-segment)
## Related validation errors
See [Instant Navigation validation errors](/docs/messages/instant-navigation-validation) for the complete reference.
---
title: Next.js encountered the unstable value Math.random() while prerendering
kind: insight
kind: error
---
<div
......@@ -14,7 +14,7 @@ kind: insight
lineHeight: '1.6',
}}
>
This Insight is part of the [Instant
This error is part of the [Instant
Navigations](https://nextjs.org/blog/next-16-3-instant-navigations) feature
introduced in Next.js 16.3. If you're new to it, start with the [Ensuring
instant navigations](/docs/app/guides/instant-navigation) guide for an
......@@ -234,20 +234,6 @@ In [`next dev`](/docs/app/api-reference/cli/next#next-dev-options), the error ov
This error fires from the prerender, not from instant-navigation validation. `Math.random()` returns a different value on every render, so the prerender can't bake it into a static shell regardless of the segment's `instant` config or [`experimental.instantInsights.validationLevel`](/docs/app/api-reference/file-conventions/route-segment-config/instant#configuring-validation-defaults). Use one of the fixes above.
## Related Insights
- [Runtime data during prerendering](/docs/messages/blocking-prerender-runtime)
- [Uncached data during prerendering](/docs/messages/blocking-prerender-dynamic)
- [URL data in a Client Component outside of Suspense](/docs/messages/blocking-prerender-client-hook)
- [Runtime data in `generateMetadata()`](/docs/messages/blocking-prerender-metadata-runtime)
- [Uncached data in `generateMetadata()`](/docs/messages/blocking-prerender-metadata-dynamic)
- [Runtime data in `generateViewport()`](/docs/messages/blocking-prerender-viewport-runtime)
- [Uncached data in `generateViewport()`](/docs/messages/blocking-prerender-viewport-dynamic)
- [`Math.random()` in a Client Component](/docs/messages/blocking-prerender-random-client)
- [`Date.now()` while prerendering](/docs/messages/blocking-prerender-current-time)
- [`Date.now()` in a Client Component](/docs/messages/blocking-prerender-current-time-client)
- [Crypto APIs while prerendering](/docs/messages/blocking-prerender-crypto)
- [Crypto APIs in a Client Component](/docs/messages/blocking-prerender-crypto-client)
- [Dynamic data during prefetching](/docs/messages/instant-link-prefetch-partial)
- [URL data outside of Suspense](/docs/messages/instant-shell-url-data)
- [Unrendered segment](/docs/messages/instant-unrendered-segment)
## Related validation errors
See [Instant Navigation validation errors](/docs/messages/instant-navigation-validation) for the complete reference.
---
title: Next.js encountered runtime data during prerendering or a navigation
kind: insight
kind: error
---
<div
......@@ -14,7 +14,7 @@ kind: insight
lineHeight: '1.6',
}}
>
This Insight is part of the [Instant
This error is part of the [Instant
Navigations](https://nextjs.org/blog/next-16-3-instant-navigations) feature
introduced in Next.js 16.3. If you're new to it, start with the [Ensuring
instant navigations](/docs/app/guides/instant-navigation) guide for an
......@@ -24,9 +24,11 @@ kind: insight
During [prerendering](/docs/app/glossary#prerendering), [`cookies()`](/docs/app/api-reference/functions/cookies), [`headers()`](/docs/app/api-reference/functions/headers), [`params`](/docs/app/api-reference/file-conventions/page#params-optional), or [`searchParams`](/docs/app/api-reference/file-conventions/page#searchparams-optional) was read outside of [`<Suspense>`](https://react.dev/reference/react/Suspense). With [Cache Components](/docs/app/api-reference/config/next-config-js/cacheComponents) enabled, Next.js can't prerender any part of the tree that depends on a per-request value, so navigations to this route block instead of being [instant](/docs/app/guides/instant-navigation).
A [`use cache`](/docs/app/api-reference/directives/use-cache) scope is also treated as runtime data when its [`expire`](/docs/app/api-reference/functions/cacheLife#expire) is under five minutes, [`stale`](/docs/app/api-reference/functions/cacheLife#stale) is under 30 seconds, or [`revalidate`](/docs/app/api-reference/functions/cacheLife#revalidate) is `0`.
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)) have different fixes. See [Next.js encountered uncached data during prerendering](/docs/messages/blocking-prerender-dynamic).
This error can also appear during a client-side navigation when the data access sits inside a [`<Suspense>`](https://react.dev/reference/react/Suspense) boundary from a parent layout but that boundary is too high. It wraps the entire segment instead of only the dynamic part, so the navigation still blocks. Push the boundary closer to the data access so the rest of the segment stays in the [static shell](/docs/app/glossary#static-shell). See [Choosing where to place the boundary](#choosing-where-to-place-the-boundary).
An ancestor [`<Suspense>`](https://react.dev/reference/react/Suspense) boundary can allow the initial route to prerender. During a later client navigation, however, runtime data without a closer boundary in the destination route delays the route update. Add a boundary near the data access so the navigation can show a fallback while the request-specific content renders. See [Choosing where to place the boundary](#choosing-where-to-place-the-boundary).
## Ways to fix this
......@@ -54,7 +56,7 @@ This error can also appear during a client-side navigation when the data access
## Wrap in or move into Suspense
Choose this fix when the value really is per-request, but the page has parts that don't depend on it. A [`<Suspense>`](https://react.dev/reference/react/Suspense) boundary lets the static shell ship instantly while the dynamic region [streams](/docs/app/glossary#streaming) in once the request value resolves.
Choose this fix when the value is per-request, but the page has parts that don't depend on it. A [`<Suspense>`](https://react.dev/reference/react/Suspense) boundary lets the static shell ship instantly while the dynamic region [streams](/docs/app/glossary#streaming) in once the request value resolves.
### Patterns
......@@ -245,6 +247,12 @@ Navigations to this route are not instant. The user waits for the full server re
- Setting [`instant`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to `false` opts only the segment that exports it out. Descendant segments are still validated by the global default.
- This export does not disable [prerendering](/docs/app/glossary#prerendering). The route still prerenders if it can. It only disables instant-navigation validation for the route.
## Other options
### Extend the cache lifetime
If a short cache triggered this error, set `expire` to at least five minutes, `stale` to at least 30 seconds, and `revalidate` above `0`. Increase the lifetime only when serving shared, older content is acceptable. If the short lifetime is intentional, keep it and place the cached work inside `<Suspense>`.
## Verifying the fix
After applying a fix, reload the route and confirm the page immediately paints meaningful UI, with any `<Suspense>` fallbacks covering only the regions that stream in. A [`<Suspense>`](https://react.dev/reference/react/Suspense) boundary placed around the whole page body can pass validation with an empty shell, which defeats the point of an instant navigation.
......@@ -260,20 +268,6 @@ Instant-navigation validation runs by default in [Cache Components](/docs/app/ap
See [Ensuring instant navigations](/docs/app/guides/instant-navigation) for the full model.
## Related Insights
- [Uncached data during prerendering](/docs/messages/blocking-prerender-dynamic)
- [URL data in a Client Component outside of Suspense](/docs/messages/blocking-prerender-client-hook)
- [Runtime data in `generateMetadata()`](/docs/messages/blocking-prerender-metadata-runtime)
- [Uncached data in `generateMetadata()`](/docs/messages/blocking-prerender-metadata-dynamic)
- [Runtime data in `generateViewport()`](/docs/messages/blocking-prerender-viewport-runtime)
- [Uncached data in `generateViewport()`](/docs/messages/blocking-prerender-viewport-dynamic)
- [`Math.random()` while prerendering](/docs/messages/blocking-prerender-random)
- [`Math.random()` in a Client Component](/docs/messages/blocking-prerender-random-client)
- [`Date.now()` while prerendering](/docs/messages/blocking-prerender-current-time)
- [`Date.now()` in a Client Component](/docs/messages/blocking-prerender-current-time-client)
- [Crypto APIs while prerendering](/docs/messages/blocking-prerender-crypto)
- [Crypto APIs in a Client Component](/docs/messages/blocking-prerender-crypto-client)
- [Dynamic data during prefetching](/docs/messages/instant-link-prefetch-partial)
- [URL data outside of Suspense](/docs/messages/instant-shell-url-data)
- [Unrendered segment](/docs/messages/instant-unrendered-segment)
## Related validation errors
See [Instant Navigation validation errors](/docs/messages/instant-navigation-validation) for the complete reference.
---
title: Next.js encountered uncached data in generateViewport()
kind: insight
kind: error
---
<div
......@@ -14,7 +14,7 @@ kind: insight
lineHeight: '1.6',
}}
>
This Insight is part of the [Instant
This error is part of the [Instant
Navigations](https://nextjs.org/blog/next-16-3-instant-navigations) feature
introduced in Next.js 16.3. If you're new to it, start with the [Ensuring
instant navigations](/docs/app/guides/instant-navigation) guide for an
......@@ -24,6 +24,8 @@ 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).
During `next build`, Next.js may link to this page when it cannot distinguish uncached data from runtime data. For a short cache, [extend the cache lifetime](/docs/messages/blocking-prerender-viewport-runtime#extend-the-cache-lifetime).
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).
## Ways to fix this
......@@ -89,7 +91,6 @@ Freshness depends on the cache configuration. The viewport stays the same until
### 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
......@@ -152,20 +153,6 @@ Instant-navigation validation runs by default in [Cache Components](/docs/app/ap
See [Ensuring instant navigations](/docs/app/guides/instant-navigation) for the full model.
## Related Insights
- [Runtime data during prerendering](/docs/messages/blocking-prerender-runtime)
- [Uncached data during prerendering](/docs/messages/blocking-prerender-dynamic)
- [URL data in a Client Component outside of Suspense](/docs/messages/blocking-prerender-client-hook)
- [Runtime data in `generateMetadata()`](/docs/messages/blocking-prerender-metadata-runtime)
- [Uncached data in `generateMetadata()`](/docs/messages/blocking-prerender-metadata-dynamic)
- [Runtime data in `generateViewport()`](/docs/messages/blocking-prerender-viewport-runtime)
- [`Math.random()` while prerendering](/docs/messages/blocking-prerender-random)
- [`Math.random()` in a Client Component](/docs/messages/blocking-prerender-random-client)
- [`Date.now()` while prerendering](/docs/messages/blocking-prerender-current-time)
- [`Date.now()` in a Client Component](/docs/messages/blocking-prerender-current-time-client)
- [Crypto APIs while prerendering](/docs/messages/blocking-prerender-crypto)
- [Crypto APIs in a Client Component](/docs/messages/blocking-prerender-crypto-client)
- [Dynamic data during prefetching](/docs/messages/instant-link-prefetch-partial)
- [URL data outside of Suspense](/docs/messages/instant-shell-url-data)
- [Unrendered segment](/docs/messages/instant-unrendered-segment)
## Related validation errors
See [Instant Navigation validation errors](/docs/messages/instant-navigation-validation) for the complete reference.
---
title: Next.js encountered runtime data in generateViewport()
kind: insight
kind: error
---
<div
......@@ -14,7 +14,7 @@ kind: insight
lineHeight: '1.6',
}}
>
This Insight is part of the [Instant
This error is part of the [Instant
Navigations](https://nextjs.org/blog/next-16-3-instant-navigations) feature
introduced in Next.js 16.3. If you're new to it, start with the [Ensuring
instant navigations](/docs/app/guides/instant-navigation) guide for an
......@@ -24,6 +24,8 @@ 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).
A [`use cache`](/docs/app/api-reference/directives/use-cache) scope is also treated as runtime data when its [`expire`](/docs/app/api-reference/functions/cacheLife#expire) is under five minutes, [`stale`](/docs/app/api-reference/functions/cacheLife#stale) is under 30 seconds, or [`revalidate`](/docs/app/api-reference/functions/cacheLife#revalidate) is `0`.
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).
## Ways to fix this
......@@ -136,6 +138,12 @@ Navigations to this route are not instant. The user waits for the full server re
- 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. [`instant = false`](/docs/app/api-reference/file-conventions/route-segment-config/instant) opts the route out of validation 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`.
## Other options
### Extend the cache lifetime
If a short cache triggered this error, set `expire` to at least five minutes, `stale` to at least 30 seconds, and `revalidate` above `0`. Increase the lifetime only when serving shared, older viewport data is acceptable.
## Verifying the fix
After applying a fix, reload the route and confirm the page immediately paints meaningful UI, with any `<Suspense>` fallbacks covering only the regions that stream in. A [`<Suspense>`](https://react.dev/reference/react/Suspense) boundary placed around the whole page body can pass validation with an empty shell, which defeats the point of an instant navigation.
......@@ -151,20 +159,6 @@ Instant-navigation validation runs by default in [Cache Components](/docs/app/ap
See [Ensuring instant navigations](/docs/app/guides/instant-navigation) for the full model.
## Related Insights
- [Runtime data during prerendering](/docs/messages/blocking-prerender-runtime)
- [Uncached data during prerendering](/docs/messages/blocking-prerender-dynamic)
- [URL data in a Client Component outside of Suspense](/docs/messages/blocking-prerender-client-hook)
- [Runtime data in `generateMetadata()`](/docs/messages/blocking-prerender-metadata-runtime)
- [Uncached data in `generateMetadata()`](/docs/messages/blocking-prerender-metadata-dynamic)
- [Uncached data in `generateViewport()`](/docs/messages/blocking-prerender-viewport-dynamic)
- [`Math.random()` while prerendering](/docs/messages/blocking-prerender-random)
- [`Math.random()` in a Client Component](/docs/messages/blocking-prerender-random-client)
- [`Date.now()` while prerendering](/docs/messages/blocking-prerender-current-time)
- [`Date.now()` in a Client Component](/docs/messages/blocking-prerender-current-time-client)
- [Crypto APIs while prerendering](/docs/messages/blocking-prerender-crypto)
- [Crypto APIs in a Client Component](/docs/messages/blocking-prerender-crypto-client)
- [Dynamic data during prefetching](/docs/messages/instant-link-prefetch-partial)
- [URL data outside of Suspense](/docs/messages/instant-shell-url-data)
- [Unrendered segment](/docs/messages/instant-unrendered-segment)
## Related validation errors
See [Instant Navigation validation errors](/docs/messages/instant-navigation-validation) for the complete reference.
......@@ -23,6 +23,20 @@ export function generateStaticParams() {
See the [`generateStaticParams` return value documentation](/docs/app/api-reference/functions/generate-static-params#returns) for the expected shape.
## With `ensureStatic`
A dynamic route that uses [`ensureStatic = 'navigation'`](/docs/app/api-reference/file-conventions/route-segment-config/ensureStatic#navigation) must export `generateStaticParams` and return at least one params object. Every object must include a value for each dynamic segment in the route.
```tsx filename="app/blog/[slug]/page.tsx"
export const ensureStatic = 'navigation'
export function generateStaticParams() {
return [{ slug: 'first-post' }, { slug: 'second-post' }]
}
```
If the route must accept values that cannot be listed at build time, first confirm that request-time rendering is intended for the entire route. Then remove `ensureStatic = 'navigation'` from every page or layout that sets it. Removing the export relaxes the static-output requirement for every segment in the route.
## Using `output: 'export'`
When your application uses `output: 'export'`, every [Dynamic Route](/docs/app/api-reference/file-conventions/dynamic-routes), such as `app/blog/[slug]/page.tsx`, must be rendered at build time.
......
......@@ -198,18 +198,4 @@ See [Ensuring instant navigations](/docs/app/guides/instant-navigation) for the
## Related Insights
- [Runtime data during prerendering](/docs/messages/blocking-prerender-runtime)
- [Uncached data during prerendering](/docs/messages/blocking-prerender-dynamic)
- [URL data in a Client Component outside of Suspense](/docs/messages/blocking-prerender-client-hook)
- [Runtime data in `generateMetadata()`](/docs/messages/blocking-prerender-metadata-runtime)
- [Uncached data in `generateMetadata()`](/docs/messages/blocking-prerender-metadata-dynamic)
- [Runtime data in `generateViewport()`](/docs/messages/blocking-prerender-viewport-runtime)
- [Uncached data in `generateViewport()`](/docs/messages/blocking-prerender-viewport-dynamic)
- [`Math.random()` while prerendering](/docs/messages/blocking-prerender-random)
- [`Math.random()` in a Client Component](/docs/messages/blocking-prerender-random-client)
- [`Date.now()` while prerendering](/docs/messages/blocking-prerender-current-time)
- [`Date.now()` in a Client Component](/docs/messages/blocking-prerender-current-time-client)
- [Crypto APIs while prerendering](/docs/messages/blocking-prerender-crypto)
- [Crypto APIs in a Client Component](/docs/messages/blocking-prerender-crypto-client)
- [URL data outside of Suspense](/docs/messages/instant-shell-url-data)
- [Unrendered segment](/docs/messages/instant-unrendered-segment)
See [Instant Navigation validation errors](/docs/messages/instant-navigation-validation) for the complete reference.
---
title: Instant Navigation validation errors
---
Instant Navigation validation checks whether a route can produce the UI required at each [navigation stage](/docs/app/glossary#navigation-stages). This page collects the errors and non-blocking insights it can report.
## Debug validation errors
Start with [`next dev`](/docs/app/guides/building#find-blocking-work) and open the affected route. The development overlay and terminal show source-mapped stack frames and rerun validation as you edit.
If the error only appears during `next build`, follow [Debug prerender errors](/docs/app/guides/building#debug-prerender-errors) to enable more detailed stack traces and code frames. You can combine `--debug-prerender` with `--debug-build-paths` to focus on specific routes.
## Static shell and prerendering
- [Runtime data during prerendering](/docs/messages/blocking-prerender-runtime)
- [Uncached data during prerendering](/docs/messages/blocking-prerender-dynamic)
- [URL data in a Client Component outside of Suspense](/docs/messages/blocking-prerender-client-hook)
- [Runtime data in `generateMetadata()`](/docs/messages/blocking-prerender-metadata-runtime)
- [Uncached data in `generateMetadata()`](/docs/messages/blocking-prerender-metadata-dynamic)
- [Runtime data in `generateViewport()`](/docs/messages/blocking-prerender-viewport-runtime)
- [Uncached data in `generateViewport()`](/docs/messages/blocking-prerender-viewport-dynamic)
- [Uncached data outside of Suspense](/docs/messages/blocking-route)
## Unstable values
- [`Math.random()` while prerendering](/docs/messages/blocking-prerender-random)
- [`Math.random()` in a Client Component](/docs/messages/blocking-prerender-random-client)
- [`Date.now()` while prerendering](/docs/messages/blocking-prerender-current-time)
- [`Date.now()` in a Client Component](/docs/messages/blocking-prerender-current-time-client)
- [Crypto APIs while prerendering](/docs/messages/blocking-prerender-crypto)
- [Crypto APIs in a Client Component](/docs/messages/blocking-prerender-crypto-client)
## Non-blocking insights
These insights identify content that is deferred to a later navigation stage without blocking navigation.
- [Dynamic data during prefetching](/docs/messages/instant-link-prefetch-partial)
- [URL data outside of Suspense](/docs/messages/instant-shell-url-data)
- [Unrendered segment](/docs/messages/instant-unrendered-segment)
## Fully static routes
These errors occur when a route uses [`ensureStatic = 'navigation'`](/docs/app/api-reference/file-conventions/route-segment-config/ensureStatic#navigation). The requirement applies even inside `<Suspense>` because the complete server-rendered route must be static.
- [Runtime data on a route that must be fully static](/docs/messages/static-route-runtime)
- [Uncached data on a route that must be fully static](/docs/messages/static-route-dynamic)
- [Runtime data in `generateMetadata()`](/docs/messages/static-metadata-runtime)
- [Uncached data in `generateMetadata()`](/docs/messages/static-metadata-dynamic)
- [Runtime data in `generateViewport()`](/docs/messages/static-viewport-runtime)
- [Uncached data in `generateViewport()`](/docs/messages/static-viewport-dynamic)
- [Missing or incomplete `generateStaticParams()`](/docs/messages/generate-static-params#with-ensurestatic)
......@@ -196,18 +196,4 @@ See [Ensuring instant navigations](/docs/app/guides/instant-navigation) for the
## Related Insights
- [Runtime data during prerendering](/docs/messages/blocking-prerender-runtime)
- [Uncached data during prerendering](/docs/messages/blocking-prerender-dynamic)
- [URL data in a Client Component outside of Suspense](/docs/messages/blocking-prerender-client-hook)
- [Runtime data in `generateMetadata()`](/docs/messages/blocking-prerender-metadata-runtime)
- [Uncached data in `generateMetadata()`](/docs/messages/blocking-prerender-metadata-dynamic)
- [Runtime data in `generateViewport()`](/docs/messages/blocking-prerender-viewport-runtime)
- [Uncached data in `generateViewport()`](/docs/messages/blocking-prerender-viewport-dynamic)
- [`Math.random()` while prerendering](/docs/messages/blocking-prerender-random)
- [`Math.random()` in a Client Component](/docs/messages/blocking-prerender-random-client)
- [`Date.now()` while prerendering](/docs/messages/blocking-prerender-current-time)
- [`Date.now()` in a Client Component](/docs/messages/blocking-prerender-current-time-client)
- [Crypto APIs while prerendering](/docs/messages/blocking-prerender-crypto)
- [Crypto APIs in a Client Component](/docs/messages/blocking-prerender-crypto-client)
- [Dynamic data during prefetching](/docs/messages/instant-link-prefetch-partial)
- [Unrendered segment](/docs/messages/instant-unrendered-segment)
See [Instant Navigation validation errors](/docs/messages/instant-navigation-validation) for the complete reference.
......@@ -186,18 +186,4 @@ See [Ensuring instant navigations](/docs/app/guides/instant-navigation) for the
## Related Insights
- [Runtime data during prerendering](/docs/messages/blocking-prerender-runtime)
- [Uncached data during prerendering](/docs/messages/blocking-prerender-dynamic)
- [URL data in a Client Component outside of Suspense](/docs/messages/blocking-prerender-client-hook)
- [Runtime data in `generateMetadata()`](/docs/messages/blocking-prerender-metadata-runtime)
- [Uncached data in `generateMetadata()`](/docs/messages/blocking-prerender-metadata-dynamic)
- [Runtime data in `generateViewport()`](/docs/messages/blocking-prerender-viewport-runtime)
- [Uncached data in `generateViewport()`](/docs/messages/blocking-prerender-viewport-dynamic)
- [`Math.random()` while prerendering](/docs/messages/blocking-prerender-random)
- [`Math.random()` in a Client Component](/docs/messages/blocking-prerender-random-client)
- [`Date.now()` while prerendering](/docs/messages/blocking-prerender-current-time)
- [`Date.now()` in a Client Component](/docs/messages/blocking-prerender-current-time-client)
- [Crypto APIs while prerendering](/docs/messages/blocking-prerender-crypto)
- [Crypto APIs in a Client Component](/docs/messages/blocking-prerender-crypto-client)
- [Dynamic data during prefetching](/docs/messages/instant-link-prefetch-partial)
- [URL data outside of Suspense](/docs/messages/instant-shell-url-data)
See [Instant Navigation validation errors](/docs/messages/instant-navigation-validation) for the complete reference.
---
title: Next.js encountered uncached data in `generateMetadata()` on a route that must be fully static
kind: error
---
<div
style={{
padding: '1.25rem 1.5rem',
border: '1px solid var(--ds-gray-400)',
borderRadius: '12px',
background: 'var(--ds-background-200)',
margin: '1.5rem 0 2rem',
fontSize: '0.95rem',
lineHeight: '1.6',
}}
>
This error is part of the [Instant
Navigations](https://nextjs.org/blog/next-16-3-instant-navigations) feature
introduced in Next.js 16.3. If you're new to it, start with the [Ensuring
instant navigations](/docs/app/guides/instant-navigation) guide.
</div>
A page or layout on this route exports [`ensureStatic`](/docs/app/api-reference/file-conventions/route-segment-config/ensureStatic) with the `'navigation'` value, requiring all server-rendered work for the route to complete during prerendering.
During [prerendering](/docs/app/glossary#prerendering), [`generateMetadata()`](/docs/app/api-reference/functions/generate-metadata) performed an uncached [`fetch()`](https://developer.mozilla.org/en-US/docs/Web/API/Window/fetch) request, database call, or [`connection()`](/docs/app/api-reference/functions/connection). The operation requires request-time server work and prevents `generateMetadata()` from being fully prerendered.
During `next build`, Next.js may link to this page when it cannot distinguish uncached data from runtime data. For a short cache, [extend the cache lifetime](/docs/messages/static-metadata-runtime#extend-the-cache-lifetime).
Request-specific reads from [`cookies()`](/docs/app/api-reference/functions/cookies), [`headers()`](/docs/app/api-reference/functions/headers), [`params`](/docs/app/api-reference/file-conventions/page#params-optional), or [`searchParams`](/docs/app/api-reference/file-conventions/page#searchparams-optional) have different fixes. See [Runtime data in `generateMetadata()` on a route that must be fully static](/docs/messages/static-metadata-runtime).
## Ways to fix this
<FixCardGrid>
<FixCard
group="cache"
title="Cache the metadata"
href="#cache-the-metadata"
snippets={[
{ text: 'async function generateMetadata() {' },
{ text: ' "use cache"', highlight: true },
{ text: ' return await cms.getMeta(…)' },
]}
/>
<FixCard
group="static"
title="Use static metadata"
href="#use-static-metadata"
snippets={[
{ text: 'export const metadata = {', highlight: true },
{ text: " title: 'My page'" },
{ text: '}' },
]}
/>
</FixCardGrid>
## Cache the metadata
Choose this fix when metadata can be shared across requests.
### Patterns
#### Add `use cache` to `generateMetadata()`
Cache `generateMetadata()` with [`use cache`](/docs/app/api-reference/directives/use-cache) and choose an appropriate [`cacheLife`](/docs/app/api-reference/functions/cacheLife) profile:
```jsx filename="app/page.jsx"
import { cacheLife } from 'next/cache'
export async function generateMetadata() {
'use cache'
cacheLife('hours')
const response = await fetch('https://api.example.com/content')
const data = await response.json()
return { title: data.title }
}
```
Learn more: [Caching with `use cache`](/docs/app/api-reference/directives/use-cache).
### Trade-off
Visitors share the cached metadata until it is revalidated.
### Gotchas
- This fix does not apply to [`connection()`](/docs/app/api-reference/functions/connection), whose purpose is to require request-time rendering.
- Caching does not make cookies, headers, parameters, or search parameters static.
## Use static metadata
Choose this fix when metadata does not need the uncached value.
### Patterns
#### Export a static metadata object
Replace `generateMetadata()` with a static [`metadata`](/docs/app/api-reference/functions/generate-metadata#the-metadata-object) export:
```jsx filename="app/dashboard/layout.jsx"
export const metadata = { title: 'My page' }
```
Learn more: [Static metadata](/docs/app/api-reference/functions/generate-metadata#the-metadata-object).
### Trade-off
The metadata is determined during prerendering rather than from the removed data source.
### Gotchas
- This fixes metadata only. Page content and other segments must also satisfy the static requirement.
- If the value must be generated for each request, first confirm that request-time rendering is intended for the entire route. See [Remove the static requirement](#remove-the-static-requirement).
## Verifying the fix
After applying a fix, rerun [`next build`](/docs/app/api-reference/cli/next#next-build-options) and confirm that the route completes prerendering. If the error also appeared in [`next dev`](/docs/app/api-reference/cli/next#next-dev-options), reload the route and confirm that the overlay clears. Wrapping the operation in Suspense or setting `instant = false` does not relax the fully static requirement.
In `next dev`, the error overlay points at the failing function with file paths and line numbers. Run [`next build --debug-prerender`](/docs/app/guides/building#debug-prerender-errors) for full user-frame stack traces and `next build --debug-build-paths /dashboard /settings` to iterate on specific routes.
## Remove the static requirement
The `'navigation'` value is usually set deliberately to guarantee static output for the entire server-rendered route. Removing it relaxes that requirement for every segment, not only metadata.
If request-time rendering is intentional for this route, remove `ensureStatic = 'navigation'` from every page or layout that sets it. The route then follows the ordinary [Cache Components](/docs/app/getting-started/caching) rendering rules.
Learn more: [Combining `ensureStatic` levels across layouts and pages](/docs/app/api-reference/file-conventions/route-segment-config/ensureStatic#combining-levels-across-layouts-and-pages).
## Related validation errors
See [Instant Navigation validation errors](/docs/messages/instant-navigation-validation) for the complete reference.
---
title: Next.js encountered runtime data in `generateMetadata()` on a route that must be fully static
kind: error
---
<div
style={{
padding: '1.25rem 1.5rem',
border: '1px solid var(--ds-gray-400)',
borderRadius: '12px',
background: 'var(--ds-background-200)',
margin: '1.5rem 0 2rem',
fontSize: '0.95rem',
lineHeight: '1.6',
}}
>
This error is part of the [Instant
Navigations](https://nextjs.org/blog/next-16-3-instant-navigations) feature
introduced in Next.js 16.3. If you're new to it, start with the [Ensuring
instant navigations](/docs/app/guides/instant-navigation) guide.
</div>
A page or layout on this route exports [`ensureStatic`](/docs/app/api-reference/file-conventions/route-segment-config/ensureStatic) with the `'navigation'` value, requiring all server-rendered work for the route to complete during prerendering.
During [prerendering](/docs/app/glossary#prerendering), [`generateMetadata()`](/docs/app/api-reference/functions/generate-metadata) read request-specific data from [`cookies()`](/docs/app/api-reference/functions/cookies), [`headers()`](/docs/app/api-reference/functions/headers), [`params`](/docs/app/api-reference/file-conventions/page#params-optional), or [`searchParams`](/docs/app/api-reference/file-conventions/page#searchparams-optional). These values are only available for a request and prevent `generateMetadata()` from being fully prerendered.
A [`use cache`](/docs/app/api-reference/directives/use-cache) scope also triggers this error when its [`expire`](/docs/app/api-reference/functions/cacheLife#expire) is under five minutes, [`stale`](/docs/app/api-reference/functions/cacheLife#stale) is under 30 seconds, or [`revalidate`](/docs/app/api-reference/functions/cacheLife#revalidate) is `0`.
Uncached [`fetch()`](https://developer.mozilla.org/en-US/docs/Web/API/Window/fetch) requests, database calls, and [`connection()`](/docs/app/api-reference/functions/connection) have different fixes. See [Uncached data in `generateMetadata()` on a route that must be fully static](/docs/messages/static-metadata-dynamic).
## Ways to fix this
<FixCardGrid>
<FixCard
group="static"
title="Use static metadata"
href="#use-static-metadata"
snippets={[
{ text: 'export const metadata = {', highlight: true },
{ text: " title: 'My page'" },
{ text: '}' },
]}
/>
</FixCardGrid>
## Use static metadata
Choose this fix when metadata does not need request-specific data.
### Patterns
#### Export a static metadata object
Replace `generateMetadata()` with a static [`metadata`](/docs/app/api-reference/functions/generate-metadata#the-metadata-object) export:
```jsx filename="app/dashboard/layout.jsx"
export const metadata = { title: 'My page' }
export default function Layout({ children }) {
return <section>{children}</section>
}
```
Learn more: [Static metadata](/docs/app/api-reference/functions/generate-metadata#the-metadata-object).
### Trade-off
The metadata is determined during prerendering rather than per request.
### Gotchas
- This fixes metadata only. Page content and other segments must also satisfy the static requirement.
- A static export cannot read `cookies()`, `headers()`, `params`, or `searchParams`.
## Other options
### Extend the cache lifetime
Set `expire` to at least five minutes, `stale` to at least 30 seconds, and `revalidate` above `0`. Increase the lifetime only when serving shared, older metadata is acceptable.
Learn more: [`cacheLife`](/docs/app/api-reference/functions/cacheLife).
## Verifying the fix
After applying a fix, rerun [`next build`](/docs/app/api-reference/cli/next#next-build-options) and confirm that the route completes prerendering. If the error also appeared in [`next dev`](/docs/app/api-reference/cli/next#next-dev-options), reload the route and confirm that the overlay clears. Wrapping the access in Suspense or setting `instant = false` does not relax the fully static requirement.
In `next dev`, the error overlay points at the failing function with file paths and line numbers. Run [`next build --debug-prerender`](/docs/app/guides/building#debug-prerender-errors) for full user-frame stack traces and `next build --debug-build-paths /dashboard /settings` to iterate on specific routes.
## Remove the static requirement
The `'navigation'` value is usually set deliberately to guarantee static output for the entire server-rendered route. Removing it relaxes that requirement for every segment, not only metadata.
If request-time rendering is intentional for this route, remove `ensureStatic = 'navigation'` from every page or layout that sets it. The route then follows the ordinary [Cache Components](/docs/app/getting-started/caching) rendering rules.
Learn more: [Combining `ensureStatic` levels across layouts and pages](/docs/app/api-reference/file-conventions/route-segment-config/ensureStatic#combining-levels-across-layouts-and-pages).
## Related validation errors
See [Instant Navigation validation errors](/docs/messages/instant-navigation-validation) for the complete reference.
---
title: Next.js encountered uncached data on a route that must be fully static
kind: error
---
<div
style={{
padding: '1.25rem 1.5rem',
border: '1px solid var(--ds-gray-400)',
borderRadius: '12px',
background: 'var(--ds-background-200)',
margin: '1.5rem 0 2rem',
fontSize: '0.95rem',
lineHeight: '1.6',
}}
>
This error is part of the [Instant
Navigations](https://nextjs.org/blog/next-16-3-instant-navigations) feature
introduced in Next.js 16.3. If you're new to it, start with the [Ensuring
instant navigations](/docs/app/guides/instant-navigation) guide.
</div>
A page or layout on this route exports [`ensureStatic`](/docs/app/api-reference/file-conventions/route-segment-config/ensureStatic) with the `'navigation'` value, requiring all server-rendered work for the route to complete during prerendering.
During [prerendering](/docs/app/glossary#prerendering), the page or layout performed an uncached [`fetch()`](https://developer.mozilla.org/en-US/docs/Web/API/Window/fetch) request, database call, or [`connection()`](/docs/app/api-reference/functions/connection). Because the operation requires request-time server work, the route cannot be fully prerendered.
During `next build`, Next.js may link to this page when it cannot distinguish uncached data from runtime data. For a short cache, [extend the cache lifetime](/docs/messages/static-route-runtime#extend-the-cache-lifetime).
Request-specific reads from [`cookies()`](/docs/app/api-reference/functions/cookies), [`headers()`](/docs/app/api-reference/functions/headers), [`params`](/docs/app/api-reference/file-conventions/page#params-optional), or [`searchParams`](/docs/app/api-reference/file-conventions/page#searchparams-optional) have different fixes. See [Runtime data on a route that must be fully static](/docs/messages/static-route-runtime).
## Ways to fix this
<FixCardGrid>
<FixCard
group="cache"
title="Cache the data"
href="#cache-the-data"
snippets={[
{ text: 'async function getData() {' },
{ text: ' "use cache"', highlight: true },
{ text: ' return await db.query(…)' },
]}
/>
<FixCard
group="remove"
title="Remove the data access"
href="#remove-the-data-access"
snippets={[
{ text: 'async function Page() {' },
{ text: '- await connection()', highlight: true },
{ text: ' return <Content />' },
]}
/>
</FixCardGrid>
## Cache the data
Choose this fix when the data can be shared across requests.
### Patterns
#### Add `use cache` to the data access
Cache the asynchronous function with [`use cache`](/docs/app/api-reference/directives/use-cache) and choose an appropriate [`cacheLife`](/docs/app/api-reference/functions/cacheLife) profile:
```jsx filename="app/page.jsx"
import { cacheLife } from 'next/cache'
export default async function Page() {
'use cache'
cacheLife('hours')
const response = await fetch('https://api.example.com/content')
const data = await response.json()
return <h1>{data.title}</h1>
}
```
Learn more: [Caching with `use cache`](/docs/app/api-reference/directives/use-cache).
### Trade-off
Visitors share the cached result until it is revalidated.
### Gotchas
- This fix does not apply to [`connection()`](/docs/app/api-reference/functions/connection), whose purpose is to require request-time rendering.
- Caching does not make request-specific cookies, headers, parameters, or search parameters static.
## Remove the data access
Choose this fix when the operation is unnecessary.
### Patterns
#### Remove the uncached operation
Remove the access rather than only removing the JSX that displays its result:
```jsx filename="app/page.jsx"
export const ensureStatic = 'navigation'
export default function Page() {
return <h1>My page</h1>
}
```
### Trade-off
Every visitor receives the same output because the removed operation no longer runs per request.
### Gotchas
- Other uncached or runtime data in the route, including layouts and metadata, must also be resolved.
- If the operation must run for each request, first confirm that request-time rendering is intended for the entire route. See [Remove the static requirement](#remove-the-static-requirement).
## Verifying the fix
After applying a fix, rerun [`next build`](/docs/app/api-reference/cli/next#next-build-options) and confirm that the route completes prerendering. If the error also appeared in [`next dev`](/docs/app/api-reference/cli/next#next-dev-options), reload the route and confirm that the overlay clears. Wrapping the operation in Suspense or setting `instant = false` does not relax the fully static requirement.
In `next dev`, the error overlay points at the failing component with file paths and line numbers. Run [`next build --debug-prerender`](/docs/app/guides/building#debug-prerender-errors) for full user-frame stack traces and `next build --debug-build-paths /dashboard /settings` to iterate on specific routes.
## Remove the static requirement
The `'navigation'` value is usually set deliberately to guarantee static output for the entire server-rendered route. Removing it relaxes that requirement for every segment, not only the code that triggered this error.
If request-time rendering is intentional for this route, remove `ensureStatic = 'navigation'` from every page or layout that sets it. The route then follows the ordinary [Cache Components](/docs/app/getting-started/caching) rendering rules.
Learn more: [Combining `ensureStatic` levels across layouts and pages](/docs/app/api-reference/file-conventions/route-segment-config/ensureStatic#combining-levels-across-layouts-and-pages).
## Related validation errors
See [Instant Navigation validation errors](/docs/messages/instant-navigation-validation) for the complete reference.
---
title: Next.js encountered runtime data on a route that must be fully static
kind: error
---
<div
style={{
padding: '1.25rem 1.5rem',
border: '1px solid var(--ds-gray-400)',
borderRadius: '12px',
background: 'var(--ds-background-200)',
margin: '1.5rem 0 2rem',
fontSize: '0.95rem',
lineHeight: '1.6',
}}
>
This error is part of the [Instant
Navigations](https://nextjs.org/blog/next-16-3-instant-navigations) feature
introduced in Next.js 16.3. If you're new to it, start with the [Ensuring
instant navigations](/docs/app/guides/instant-navigation) guide.
</div>
A page or layout on this route exports [`ensureStatic`](/docs/app/api-reference/file-conventions/route-segment-config/ensureStatic) with the `'navigation'` value, requiring all server-rendered work for the route to complete during prerendering.
During [prerendering](/docs/app/glossary#prerendering), the page or layout read request-specific data from [`cookies()`](/docs/app/api-reference/functions/cookies), [`headers()`](/docs/app/api-reference/functions/headers), [`params`](/docs/app/api-reference/file-conventions/page#params-optional), or [`searchParams`](/docs/app/api-reference/file-conventions/page#searchparams-optional). Because these values are only available for a request, the route cannot be fully prerendered.
A [`use cache`](/docs/app/api-reference/directives/use-cache) scope also triggers this error when its [`expire`](/docs/app/api-reference/functions/cacheLife#expire) is under five minutes, [`stale`](/docs/app/api-reference/functions/cacheLife#stale) is under 30 seconds, or [`revalidate`](/docs/app/api-reference/functions/cacheLife#revalidate) is `0`.
Uncached [`fetch()`](https://developer.mozilla.org/en-US/docs/Web/API/Window/fetch) requests, database calls, and [`connection()`](/docs/app/api-reference/functions/connection) have different fixes. See [Uncached data on a route that must be fully static](/docs/messages/static-route-dynamic).
## Ways to fix this
<FixCardGrid>
<FixCard
group="remove"
title="Remove the data access"
href="#remove-the-data-access"
snippets={[
{ text: 'async function Page() {' },
{ text: '- const store = await cookies()', highlight: true },
{ text: ' return <Content />' },
]}
/>
<FixCard
group="client"
title="Read search parameters on the client"
href="#read-search-parameters-on-the-client"
snippets={[
{ text: "'use client'" },
{ text: 'const params = useSearchParams()', highlight: true },
{ text: "return <p>{params.get('q')}</p>" },
]}
/>
</FixCardGrid>
## Remove the data access
Choose this fix when the content does not need to vary by request. Replace the request-specific value with a value available during prerendering.
### Patterns
#### Remove the request-specific read
Remove the runtime API call and use a value that can be determined during prerendering.
```jsx filename="app/page.jsx"
export const ensureStatic = 'navigation'
export default function Page() {
return <h1>My page</h1>
}
```
### Trade-off
Every visitor receives the same value because the route no longer reads request-specific data.
### Gotchas
- This fix applies to `cookies()`, `headers()`, and other removable reads. It does not provide replacement values when the content must vary by request.
## Read search parameters on the client
Choose this fix when only browser UI needs the query string.
### Patterns
#### Read the query string in a Client Component
Use [`useSearchParams()`](/docs/app/api-reference/functions/use-search-params) instead of the page's server-side `searchParams` prop:
```jsx filename="app/search/query.jsx"
'use client'
import { useSearchParams } from 'next/navigation'
export default function Query() {
const searchParams = useSearchParams()
return <p>Query: {searchParams.get('q')}</p>
}
```
Learn more: [`useSearchParams()`](/docs/app/api-reference/functions/use-search-params).
Render the Client Component inside [`Suspense`](https://react.dev/reference/react/Suspense). Do not pass the server's `searchParams` promise to it.
### Trade-off
The prerender includes the fallback, and the query-dependent UI renders in the browser.
### Gotchas
- Adding `'use client'` alone does not fix this error. Remove the server-side read and use the client hook.
- Do not pass the server's `searchParams` promise to the Client Component.
- This fix applies only to `searchParams`. It does not replace cookies, headers, or route parameters.
## Other options
### Extend the cache lifetime
Set `expire` to at least five minutes, `stale` to at least 30 seconds, and `revalidate` above `0`. Increase the lifetime only when serving shared, older content is acceptable.
Learn more: [`cacheLife`](/docs/app/api-reference/functions/cacheLife).
## Verifying the fix
After applying a fix, rerun [`next build`](/docs/app/api-reference/cli/next#next-build-options) and confirm that the route completes prerendering. If the error also appeared in [`next dev`](/docs/app/api-reference/cli/next#next-dev-options), reload the route and confirm that the overlay clears. Wrapping the access in Suspense or setting `instant = false` does not relax the fully static requirement.
In `next dev`, the error overlay points at the failing component with file paths and line numbers. Run [`next build --debug-prerender`](/docs/app/guides/building#debug-prerender-errors) for full user-frame stack traces and `next build --debug-build-paths /dashboard /settings` to iterate on specific routes.
## Remove the static requirement
The `'navigation'` value is usually set deliberately to guarantee static output for the entire server-rendered route. Removing it relaxes that requirement for every segment, not only the code that triggered this error.
If request-time rendering is intentional for this route, remove `ensureStatic = 'navigation'` from every page or layout that sets it. The route then follows the ordinary [Cache Components](/docs/app/getting-started/caching) rendering rules.
Learn more: [Combining `ensureStatic` levels across layouts and pages](/docs/app/api-reference/file-conventions/route-segment-config/ensureStatic#combining-levels-across-layouts-and-pages).
## Related validation errors
See [Instant Navigation validation errors](/docs/messages/instant-navigation-validation) for the complete reference.
---
title: Next.js encountered uncached data in `generateViewport()` on a route that must be fully static
kind: error
---
<div
style={{
padding: '1.25rem 1.5rem',
border: '1px solid var(--ds-gray-400)',
borderRadius: '12px',
background: 'var(--ds-background-200)',
margin: '1.5rem 0 2rem',
fontSize: '0.95rem',
lineHeight: '1.6',
}}
>
This error is part of the [Instant
Navigations](https://nextjs.org/blog/next-16-3-instant-navigations) feature
introduced in Next.js 16.3. If you're new to it, start with the [Ensuring
instant navigations](/docs/app/guides/instant-navigation) guide.
</div>
A page or layout on this route exports [`ensureStatic`](/docs/app/api-reference/file-conventions/route-segment-config/ensureStatic) with the `'navigation'` value, requiring all server-rendered work for the route to complete during prerendering.
During [prerendering](/docs/app/glossary#prerendering), [`generateViewport()`](/docs/app/api-reference/functions/generate-viewport) performed an uncached [`fetch()`](https://developer.mozilla.org/en-US/docs/Web/API/Window/fetch) request, database call, or [`connection()`](/docs/app/api-reference/functions/connection). The operation requires request-time server work and prevents `generateViewport()` from being fully prerendered.
During `next build`, Next.js may link to this page when it cannot distinguish uncached data from runtime data. For a short cache, [extend the cache lifetime](/docs/messages/static-viewport-runtime#extend-the-cache-lifetime).
Request-specific reads from [`cookies()`](/docs/app/api-reference/functions/cookies), [`headers()`](/docs/app/api-reference/functions/headers), [`params`](/docs/app/api-reference/file-conventions/page#params-optional), or [`searchParams`](/docs/app/api-reference/file-conventions/page#searchparams-optional) have different fixes. See [Runtime data in `generateViewport()` on a route that must be fully static](/docs/messages/static-viewport-runtime).
## Ways to fix this
<FixCardGrid>
<FixCard
group="cache"
title="Cache the viewport"
href="#cache-the-viewport"
snippets={[
{ text: 'async function generateViewport() {' },
{ text: ' "use cache"', highlight: true },
{ text: ' return await cms.getViewport(…)' },
]}
/>
<FixCard
group="static"
title="Use static viewport"
href="#use-static-viewport"
snippets={[
{ text: 'export const viewport = {', highlight: true },
{ text: " themeColor: 'black'" },
{ text: '}' },
]}
/>
</FixCardGrid>
## Cache the viewport
Choose this fix when viewport data can be shared across requests.
### Patterns
#### Add `use cache` to `generateViewport()`
Cache `generateViewport()` with [`use cache`](/docs/app/api-reference/directives/use-cache) and choose an appropriate [`cacheLife`](/docs/app/api-reference/functions/cacheLife) profile:
```jsx filename="app/page.jsx"
import { cacheLife } from 'next/cache'
export async function generateViewport() {
'use cache'
cacheLife('hours')
const response = await fetch('https://api.example.com/content')
const data = await response.json()
return { themeColor: data.themeColor }
}
```
Learn more: [Caching with `use cache`](/docs/app/api-reference/directives/use-cache).
### Trade-off
Visitors share the cached viewport data until it is revalidated.
### Gotchas
- This fix does not apply to [`connection()`](/docs/app/api-reference/functions/connection), whose purpose is to require request-time rendering.
- Caching does not make cookies, headers, parameters, or search parameters static.
## Use static viewport
Choose this fix when viewport settings do not need the uncached value.
### Patterns
#### Export a static viewport object
Replace `generateViewport()` with a static [`viewport`](/docs/app/api-reference/functions/generate-viewport#the-viewport-object) export:
```jsx filename="app/dashboard/layout.jsx"
export const viewport = { themeColor: 'black' }
```
Learn more: [Static viewport](/docs/app/api-reference/functions/generate-viewport#the-viewport-object).
### Trade-off
The viewport is determined during prerendering rather than from the removed data source.
### Gotchas
- This fixes viewport settings only. Page content, metadata, and other segments must also satisfy the static requirement.
- If the value must be generated for each request, first confirm that request-time rendering is intended for the entire route. See [Remove the static requirement](#remove-the-static-requirement).
## Verifying the fix
After applying a fix, rerun [`next build`](/docs/app/api-reference/cli/next#next-build-options) and confirm that the route completes prerendering. If the error also appeared in [`next dev`](/docs/app/api-reference/cli/next#next-dev-options), reload the route and confirm that the overlay clears. Wrapping the operation in Suspense or setting `instant = false` does not relax the fully static requirement.
In `next dev`, the error overlay points at the failing function with file paths and line numbers. Run [`next build --debug-prerender`](/docs/app/guides/building#debug-prerender-errors) for full user-frame stack traces and `next build --debug-build-paths /dashboard /settings` to iterate on specific routes.
## Remove the static requirement
The `'navigation'` value is usually set deliberately to guarantee static output for the entire server-rendered route. Removing it relaxes that requirement for every segment, not only viewport settings.
If request-time rendering is intentional for this route, remove `ensureStatic = 'navigation'` from every page or layout that sets it. The route then follows the ordinary [Cache Components](/docs/app/getting-started/caching) rendering rules.
Learn more: [Combining `ensureStatic` levels across layouts and pages](/docs/app/api-reference/file-conventions/route-segment-config/ensureStatic#combining-levels-across-layouts-and-pages).
## Related validation errors
See [Instant Navigation validation errors](/docs/messages/instant-navigation-validation) for the complete reference.
---
title: Next.js encountered runtime data in `generateViewport()` on a route that must be fully static
kind: error
---
<div
style={{
padding: '1.25rem 1.5rem',
border: '1px solid var(--ds-gray-400)',
borderRadius: '12px',
background: 'var(--ds-background-200)',
margin: '1.5rem 0 2rem',
fontSize: '0.95rem',
lineHeight: '1.6',
}}
>
This error is part of the [Instant
Navigations](https://nextjs.org/blog/next-16-3-instant-navigations) feature
introduced in Next.js 16.3. If you're new to it, start with the [Ensuring
instant navigations](/docs/app/guides/instant-navigation) guide.
</div>
A page or layout on this route exports [`ensureStatic`](/docs/app/api-reference/file-conventions/route-segment-config/ensureStatic) with the `'navigation'` value, requiring all server-rendered work for the route to complete during prerendering.
During [prerendering](/docs/app/glossary#prerendering), [`generateViewport()`](/docs/app/api-reference/functions/generate-viewport) read request-specific data from [`cookies()`](/docs/app/api-reference/functions/cookies), [`headers()`](/docs/app/api-reference/functions/headers), [`params`](/docs/app/api-reference/file-conventions/page#params-optional), or [`searchParams`](/docs/app/api-reference/file-conventions/page#searchparams-optional). These values are only available for a request and prevent `generateViewport()` from being fully prerendered.
A [`use cache`](/docs/app/api-reference/directives/use-cache) scope also triggers this error when its [`expire`](/docs/app/api-reference/functions/cacheLife#expire) is under five minutes, [`stale`](/docs/app/api-reference/functions/cacheLife#stale) is under 30 seconds, or [`revalidate`](/docs/app/api-reference/functions/cacheLife#revalidate) is `0`.
Uncached [`fetch()`](https://developer.mozilla.org/en-US/docs/Web/API/Window/fetch) requests, database calls, and [`connection()`](/docs/app/api-reference/functions/connection) have different fixes. See [Uncached data in `generateViewport()` on a route that must be fully static](/docs/messages/static-viewport-dynamic).
## Ways to fix this
<FixCardGrid>
<FixCard
group="static"
title="Use static viewport"
href="#use-static-viewport"
snippets={[
{ text: 'export const viewport = {', highlight: true },
{ text: " themeColor: 'black'" },
{ text: '}' },
]}
/>
</FixCardGrid>
## Use static viewport
Choose this fix when viewport settings do not need request-specific data.
### Patterns
#### Export a static viewport object
Replace `generateViewport()` with a static [`viewport`](/docs/app/api-reference/functions/generate-viewport#the-viewport-object) export:
```jsx filename="app/dashboard/layout.jsx"
export const viewport = { themeColor: 'black' }
export default function Layout({ children }) {
return <section>{children}</section>
}
```
Learn more: [Static viewport](/docs/app/api-reference/functions/generate-viewport#the-viewport-object).
### Trade-off
The viewport is determined during prerendering rather than per request.
### Gotchas
- This fixes viewport settings only. Page content, metadata, and other segments must also satisfy the static requirement.
- A static export cannot read `cookies()`, `headers()`, `params`, or `searchParams`.
## Other options
### Extend the cache lifetime
Set `expire` to at least five minutes, `stale` to at least 30 seconds, and `revalidate` above `0`. Increase the lifetime only when serving shared, older viewport data is acceptable.
Learn more: [`cacheLife`](/docs/app/api-reference/functions/cacheLife).
## Verifying the fix
After applying a fix, rerun [`next build`](/docs/app/api-reference/cli/next#next-build-options) and confirm that the route completes prerendering. If the error also appeared in [`next dev`](/docs/app/api-reference/cli/next#next-dev-options), reload the route and confirm that the overlay clears. Wrapping the access in Suspense or setting `instant = false` does not relax the fully static requirement.
In `next dev`, the error overlay points at the failing function with file paths and line numbers. Run [`next build --debug-prerender`](/docs/app/guides/building#debug-prerender-errors) for full user-frame stack traces and `next build --debug-build-paths /dashboard /settings` to iterate on specific routes.
## Remove the static requirement
The `'navigation'` value is usually set deliberately to guarantee static output for the entire server-rendered route. Removing it relaxes that requirement for every segment, not only viewport settings.
If request-time rendering is intentional for this route, remove `ensureStatic = 'navigation'` from every page or layout that sets it. The route then follows the ordinary [Cache Components](/docs/app/getting-started/caching) rendering rules.
Learn more: [Combining `ensureStatic` levels across layouts and pages](/docs/app/api-reference/file-conventions/route-segment-config/ensureStatic#combining-levels-across-layouts-and-pages).
## Related validation errors
See [Instant Navigation validation errors](/docs/messages/instant-navigation-validation) for the complete reference.
......@@ -26,8 +26,11 @@ export function ErrorMessage({ errorMessage, errorType }: ErrorMessageProps) {
// Instant errors are formatted specifically for the overlay rather than
// passed through from the console, so we don't truncate them — they rely
// on scroll overflow instead.
const shouldTruncate =
isTooTall && errorType !== 'Instant' && errorType !== 'Blocking Route'
const isGuidanceError =
errorType === 'Instant' ||
errorType === 'Blocking Route' ||
errorType === 'Static Route'
const shouldTruncate = isTooTall && !isGuidanceError
return (
<>
......@@ -35,7 +38,7 @@ export function ErrorMessage({ errorMessage, errorType }: ErrorMessageProps) {
<div
ref={messageRef}
id="nextjs__container_errors_desc"
className={`nextjs__container_errors_desc ${shouldTruncate && !isExpanded ? 'truncated' : ''} ${errorType === 'Instant' || errorType === 'Blocking Route' ? 'nextjs__container_errors_desc_instant' : ''}`}
className={`nextjs__container_errors_desc ${shouldTruncate && !isExpanded ? 'truncated' : ''} ${isGuidanceError ? 'nextjs__container_errors_desc_instant' : ''}`}
>
{errorMessage}
</div>
......
......@@ -4,6 +4,7 @@ export type ErrorType =
| `Console ${string}`
| `Recoverable ${string}`
| 'Blocking Route'
| 'Static Route'
| 'Ambiguous Metadata'
| 'Instant'
......
......@@ -16,15 +16,31 @@ import {
} from '../../../../server/app-render/blocking-route-messages'
import { createLinkPrefetchPartialError } from '../../../../shared/lib/instant-messages'
import {
EXPLANATIONS,
FIX_CARD_GROUPS,
SYNC_IO_DOCS,
SYNC_IO_CLIENT_DOCS,
getCards,
getStaticRouteDocsUrl,
type FixCardGroup,
type GuidanceKind,
type GuidanceVariant,
} from './instant-guidance-data'
describe('static route explanations', () => {
it('matches the fully static build guidance', () => {
expect(EXPLANATIONS['static-route']).toBe(
'This route is configured to be fully static, but data prevents it from being fully prerendered.'
)
expect(EXPLANATIONS['static-metadata']).toBe(
'This route is configured to be fully static, but data prevents its metadata from being fully prerendered.'
)
expect(EXPLANATIONS['static-viewport']).toBe(
'This route is configured to be fully static, but data prevents its viewport from being fully prerendered.'
)
})
})
const GUIDANCE_VARIANTS = [
'runtime',
'link',
......@@ -33,7 +49,9 @@ const GUIDANCE_VARIANTS = [
] as const satisfies GuidanceVariant[]
function tagsFromMessage(message: string): string[] {
return Array.from(message.matchAll(/^\s*-\s*\[([a-z]+)\]/gm)).map((m) => m[1])
return Array.from(message.matchAll(/^\s*-\s*\[([a-z-]+)\]/gm)).map(
(m) => m[1]
)
}
function groupsFromCards(
......@@ -148,6 +166,27 @@ describe('instant-guidance-data card ordering', () => {
})
describe('instant-guidance-data card links', () => {
it('links each static error variant to its focused page', () => {
expect(getStaticRouteDocsUrl('static-route', 'runtime')).toBe(
'https://nextjs.org/docs/messages/static-route-runtime'
)
expect(getStaticRouteDocsUrl('static-route', 'dynamic')).toBe(
'https://nextjs.org/docs/messages/static-route-dynamic'
)
expect(getStaticRouteDocsUrl('static-metadata', 'runtime')).toBe(
'https://nextjs.org/docs/messages/static-metadata-runtime'
)
expect(getStaticRouteDocsUrl('static-metadata', 'dynamic')).toBe(
'https://nextjs.org/docs/messages/static-metadata-dynamic'
)
expect(getStaticRouteDocsUrl('static-viewport', 'runtime')).toBe(
'https://nextjs.org/docs/messages/static-viewport-runtime'
)
expect(getStaticRouteDocsUrl('static-viewport', 'dynamic')).toBe(
'https://nextjs.org/docs/messages/static-viewport-dynamic'
)
})
it('every card.link ends with #card.id', () => {
type Item = [GuidanceKind, GuidanceVariant]
const variants: Array<Item> = [
......@@ -157,6 +196,12 @@ describe('instant-guidance-data card links', () => {
['client-hook', 'runtime'],
['unrendered-segment', 'runtime'],
['link-prefetch-partial', 'runtime'],
['static-route', 'runtime'],
['static-route', 'dynamic'],
['static-metadata', 'runtime'],
['static-metadata', 'dynamic'],
['static-viewport', 'runtime'],
['static-viewport', 'dynamic'],
]
for (const [kind, variant] of variants) {
for (const card of getCards(kind, variant)) {
......@@ -184,6 +229,12 @@ describe('instant-guidance-data card invariants', () => {
['client-hook', 'runtime'],
['unrendered-segment', 'runtime'],
['link-prefetch-partial', 'runtime'],
['static-route', 'runtime'],
['static-route', 'dynamic'],
['static-metadata', 'runtime'],
['static-metadata', 'dynamic'],
['static-viewport', 'runtime'],
['static-viewport', 'dynamic'],
]
for (const [kind, variant, cause] of variants) {
cards.push(...getCards(kind, variant, cause))
......@@ -247,6 +298,12 @@ describe('instant-guidance-data dispatcher', () => {
['client-hook', 'runtime'],
['unrendered-segment', 'runtime'],
['link-prefetch-partial', 'runtime'],
['static-route', 'runtime'],
['static-route', 'dynamic'],
['static-metadata', 'runtime'],
['static-metadata', 'dynamic'],
['static-viewport', 'runtime'],
['static-viewport', 'dynamic'],
]
for (const [kind, variant] of variants) {
for (const card of getCards(kind, variant)) used.add(card.group)
......
......@@ -13,6 +13,7 @@ export type FixCardGroup =
| 'render'
| 'upgrade'
| 'disable'
| 'remove'
export type FixCardIcon =
| 'align-left'
......@@ -44,6 +45,7 @@ export const FIX_CARD_GROUPS: Record<
render: { label: 'Render', color: 'gray', icon: 'layout' },
upgrade: { label: 'Upgrade', color: 'amber', icon: 'arrow-up' },
disable: { label: 'Disable', color: 'gray', icon: 'minus' },
remove: { label: 'Remove', color: 'red', icon: 'minus' },
}
export type FixCard = {
......@@ -680,7 +682,166 @@ const syncClientCryptoCards: FixCard[] = [
},
]
const staticRouteRuntimeCards: FixCard[] = [
{
id: 'remove-the-data-access',
title: 'Remove the data access',
group: 'remove',
snippets: [
{ text: 'async function Page() {' },
{ text: '- const store = await cookies()', highlight: true },
{ text: ' return <Content />' },
],
copyable: true,
link: 'https://nextjs.org/docs/messages/static-route-runtime#remove-the-data-access',
},
{
id: 'read-search-parameters-on-the-client',
title: 'Read search parameters on the client',
group: 'client',
snippets: [
{ text: "'use client'" },
{ text: 'const params = useSearchParams()', highlight: true },
{ text: "return <p>{params.get('q')}</p>" },
],
copyable: true,
link: 'https://nextjs.org/docs/messages/static-route-runtime#read-search-parameters-on-the-client',
},
]
const staticRouteDynamicCards: FixCard[] = [
{
id: 'cache-the-data',
title: 'Cache the data',
group: 'cache',
snippets: [
{
text: 'async function getData() {',
},
{
text: ' "use cache"',
highlight: true,
},
{
text: ' return await db.query(\u2026)',
},
],
copyable: true,
link: 'https://nextjs.org/docs/messages/static-route-dynamic#cache-the-data',
},
{
id: 'remove-the-data-access',
title: 'Remove the data access',
group: 'remove',
snippets: [
{ text: 'async function Page() {' },
{ text: '- await connection()', highlight: true },
{ text: ' return <Content />' },
],
copyable: true,
link: 'https://nextjs.org/docs/messages/static-route-dynamic#remove-the-data-access',
},
]
const staticMetadataRuntimeCards: FixCard[] = [
{
id: 'use-static-metadata',
title: 'Use static metadata',
group: 'static',
snippets: [
{ text: 'export const metadata = {', highlight: true },
{ text: " title: 'My page'" },
{ text: '}' },
],
copyable: true,
link: 'https://nextjs.org/docs/messages/static-metadata-runtime#use-static-metadata',
},
]
const staticMetadataDynamicCards: FixCard[] = [
{
id: 'cache-the-metadata',
title: 'Cache the metadata',
group: 'cache',
snippets: [
{
text: 'async function generateMetadata() {',
},
{
text: ' "use cache"',
highlight: true,
},
{
text: ' return await cms.getMeta(\u2026)',
},
],
copyable: true,
link: 'https://nextjs.org/docs/messages/static-metadata-dynamic#cache-the-metadata',
},
{
id: 'use-static-metadata',
title: 'Use static metadata',
group: 'static',
snippets: [
{ text: 'export const metadata = {', highlight: true },
{ text: " title: 'My page'" },
{ text: '}' },
],
copyable: true,
link: 'https://nextjs.org/docs/messages/static-metadata-dynamic#use-static-metadata',
},
]
const staticViewportRuntimeCards: FixCard[] = [
{
id: 'use-static-viewport',
title: 'Use static viewport',
group: 'static',
snippets: [
{ text: 'export const viewport = {', highlight: true },
{ text: " themeColor: 'black'" },
{ text: '}' },
],
copyable: true,
link: 'https://nextjs.org/docs/messages/static-viewport-runtime#use-static-viewport',
},
]
const staticViewportDynamicCards: FixCard[] = [
{
id: 'cache-the-viewport',
title: 'Cache the viewport',
group: 'cache',
snippets: [
{
text: 'async function generateViewport() {',
},
{
text: ' "use cache"',
highlight: true,
},
{
text: ' return await cms.getViewport(\u2026)',
},
],
copyable: true,
link: 'https://nextjs.org/docs/messages/static-viewport-dynamic#cache-the-viewport',
},
{
id: 'use-static-viewport',
title: 'Use static viewport',
group: 'static',
snippets: [
{ text: 'export const viewport = {', highlight: true },
{ text: " themeColor: 'black'" },
{ text: '}' },
],
copyable: true,
link: 'https://nextjs.org/docs/messages/static-viewport-dynamic#use-static-viewport',
},
]
export type GuidanceKind =
| 'static-route'
| 'static-metadata'
| 'static-viewport'
| 'blocking-route'
| 'client-hook'
| 'metadata'
......@@ -693,6 +854,9 @@ export type GuidanceKind =
export type GuidanceVariant = 'link' | 'runtime' | 'navigation' | 'dynamic'
export const DOCS_URLS: Record<GuidanceKind, string> = {
'static-viewport': 'https://nextjs.org/docs/messages/static-viewport',
'static-metadata': 'https://nextjs.org/docs/messages/static-metadata',
'static-route': 'https://nextjs.org/docs/messages/static-route',
'blocking-route': 'https://nextjs.org/docs/messages/blocking-route',
'client-hook':
'https://nextjs.org/docs/messages/blocking-prerender-client-hook',
......@@ -798,6 +962,12 @@ export const SYNC_IO_CLIENT_DOCS: Record<string, string> = {
}
export const EXPLANATIONS: Record<GuidanceKind, string> = {
'static-viewport':
'This route is configured to be fully static, but data prevents its viewport from being fully prerendered.',
'static-metadata':
'This route is configured to be fully static, but data prevents its metadata from being fully prerendered.',
'static-route':
'This route is configured to be fully static, but data prevents it from being fully prerendered.',
'blocking-route':
'This prevents the route from being prerendered, blocking navigation and leading to a slower user experience.',
'client-hook':
......@@ -869,6 +1039,21 @@ export function getCards(
cause?: string
): FixCard[] {
switch (kind) {
case 'static-viewport':
return variant === 'runtime'
? staticViewportRuntimeCards
: staticViewportDynamicCards
case 'static-metadata':
return variant === 'runtime'
? staticMetadataRuntimeCards
: staticMetadataDynamicCards
case 'static-route':
return variant === 'runtime'
? staticRouteRuntimeCards
: staticRouteDynamicCards
case 'blocking-route': {
switch (variant) {
case 'link':
......@@ -925,3 +1110,13 @@ export function getCards(
return kind satisfies never
}
}
export function getStaticRouteDocsUrl(
kind: GuidanceKind,
variant: GuidanceVariant
): string {
if (variant === 'runtime' || variant === 'dynamic') {
return `${DOCS_URLS[kind]}-${variant}`
}
return DOCS_URLS[kind]
}
......@@ -26,6 +26,7 @@ import {
SYNC_IO_CLIENT_DOCS,
SYNC_IO_DOCS,
getCards,
getStaticRouteDocsUrl,
type FixCard,
type FixCardGroup,
type FixCardIcon,
......@@ -247,6 +248,11 @@ export function InstantGuidance({
const cards = getCards(kind, variant, cause)
let docsUrl: string
switch (kind) {
case 'static-route':
case 'static-metadata':
case 'static-viewport':
docsUrl = getStaticRouteDocsUrl(kind, variant)
break
case 'sync-io':
docsUrl = (cause ? SYNC_IO_DOCS[cause] : undefined) ?? DOCS_URLS[kind]
break
......@@ -316,6 +322,13 @@ export function InstantHeaderExplanation({
resolvedDocsUrl = BLOCKING_METADATA_DOCS_URLS[variant ?? 'dynamic']
} else if (!resolvedDocsUrl && kind === 'viewport') {
resolvedDocsUrl = BLOCKING_VIEWPORT_DOCS_URLS[variant ?? 'dynamic']
} else if (
!resolvedDocsUrl &&
(kind === 'static-route' ||
kind === 'static-metadata' ||
kind === 'static-viewport')
) {
resolvedDocsUrl = getStaticRouteDocsUrl(kind, variant ?? 'dynamic')
} else if (!resolvedDocsUrl && kind) {
resolvedDocsUrl = DOCS_URLS[kind]
}
......
import {
createRuntimeBodyErrorInStaticRoute,
createDynamicBodyErrorInStaticRoute,
createNonPrerenderableBodyErrorInStaticRoute,
createRuntimeMetadataErrorInStaticRoute,
createDynamicMetadataErrorInStaticRoute,
createNonPrerenderableMetadataErrorInStaticRoute,
createRuntimeViewportErrorInStaticRoute,
createDynamicViewportErrorInStaticRoute,
createNonPrerenderableViewportErrorInStaticRoute,
createDynamicBodyError,
createDynamicBodyErrorInNavigation,
createDynamicMetadataError,
......@@ -24,7 +33,10 @@ import {
type SyncIOApiType,
} from '../../../server/app-render/sync-io-messages'
import { ClientHookDynamicError } from '../../../server/dynamic-rendering-utils'
import { getCards } from '../components/instant/instant-guidance-data'
import {
getCards,
getStaticRouteDocsUrl,
} from '../components/instant/instant-guidance-data'
import {
deriveCauseFromCodeFrame,
getBlockingRouteErrorDetails,
......@@ -771,3 +783,65 @@ describe('deriveCauseFromCodeFrame', () => {
).toBeUndefined()
})
})
describe('fully static route errors', () => {
it.each([
[createRuntimeBodyErrorInStaticRoute, 'static-route', 'runtime'],
[createDynamicBodyErrorInStaticRoute, 'static-route', 'dynamic'],
[createNonPrerenderableBodyErrorInStaticRoute, 'static-route', 'dynamic'],
[createRuntimeMetadataErrorInStaticRoute, 'static-metadata', 'runtime'],
[createDynamicMetadataErrorInStaticRoute, 'static-metadata', 'dynamic'],
[
createNonPrerenderableMetadataErrorInStaticRoute,
'static-metadata',
'dynamic',
],
[createRuntimeViewportErrorInStaticRoute, 'static-viewport', 'runtime'],
[createDynamicViewportErrorInStaticRoute, 'static-viewport', 'dynamic'],
[
createNonPrerenderableViewportErrorInStaticRoute,
'static-viewport',
'dynamic',
],
] as const)('classifies %p as %s (%s)', (createError, kind, variant) => {
const error = createError(ROUTE)
expect(getBlockingRouteErrorDetails(error)).toEqual({
type: 'static-route',
kind,
variant,
headline: error.message.split('\n')[0].replace(`Route "${ROUTE}": `, ''),
})
// This is a build constraint, not optional instant-navigation validation.
expect(isInstantNavigationError(error)).toBe(false)
const cards = getCards(kind, variant)
expect(cards.length).toBeGreaterThan(0)
expect(cards.map((card) => card.group)).not.toContain('stream')
expect(cards.map((card) => card.group)).not.toContain('block')
expect(cards.map((card) => card.group)).toEqual(
Array.from(
error.message.matchAll(/^\s*-\s*\[([a-z-]+)\]/gm),
(match) => match[1]
)
)
for (const card of cards) {
expect(card.link?.split('#')[0]).toBe(
getStaticRouteDocsUrl(kind, variant)
)
}
})
it.each(['static-route', 'static-metadata', 'static-viewport'] as const)(
'does not infer card filtering from the code frame for %s',
(kind) => {
const cause = deriveCauseFromCodeFrame(
kind,
'dynamic',
'> 4 | await connection()'
)
expect(cause).toBeUndefined()
expect(getCards(kind, 'dynamic', cause)).toEqual(
getCards(kind, 'dynamic')
)
}
)
})
......@@ -101,6 +101,7 @@ export function getErrorTypeLabel(
if (errorDetails.type === 'blocking-route') {
return errorDetails.inNavigation ? `Instant` : `Blocking Route`
}
if (errorDetails.type === 'static-route') return 'Static Route'
if (errorDetails.type === 'client-hook') {
return `Blocking Route`
}
......@@ -135,6 +136,7 @@ type ErrorDetails =
| NoErrorDetails
| HydrationErrorDetails
| BlockingRouteErrorDetails
| StaticRouteErrorDetails
| ClientHookErrorDetails
| DynamicMetadataErrorDetails
| DynamicViewportErrorDetails
......@@ -160,6 +162,13 @@ type BlockingRouteErrorDetails = {
inNavigation: boolean
}
type StaticRouteErrorDetails = {
type: 'static-route'
kind: 'static-route' | 'static-metadata' | 'static-viewport'
variant: GuidanceVariant
headline: string
}
type ClientHookErrorDetails = {
type: 'client-hook'
expression: string
......@@ -434,6 +443,19 @@ export function getBlockingRouteErrorDetails(
const message = error.message
const inNavigation = isBlockingRouteInNavError(message)
const staticRouteMatch =
/https:\/\/nextjs\.org\/docs\/messages\/static-(route|metadata|viewport)\b/.exec(
message
)
if (staticRouteMatch) {
return {
type: 'static-route',
kind: `static-${staticRouteMatch[1]}` as StaticRouteErrorDetails['kind'],
variant: getGuidanceVariant(message),
headline: message.split('\n')[0].replace(/^Route "[^"]*": /, ''),
}
}
const clientHookMatch =
/Next\.js encountered URL data `([^`]+)` in a Client Component outside of `<Suspense>`\./.exec(
message
......@@ -999,6 +1021,51 @@ export function Errors({
</Suspense>
</ErrorOverlayLayout>
)
case 'static-route': {
return (
<ErrorOverlayLayout
errorType={errorType}
errorMessage={
<HotlinkedText
text={errorDetails.headline}
matcher={matchLinkType}
/>
}
headerChildren={
<InstantHeaderExplanation
kind={errorDetails.kind}
variant={errorDetails.variant}
/>
}
renderTabBar={renderTabBar}
canGoPrevious={canGoPrevious}
canGoNext={canGoNext}
onPrevious={handlePrevious}
onNext={handleNext}
onClose={isServerError ? undefined : onClose}
debugInfo={debugInfo}
error={error}
runtimeErrors={activeErrors}
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}
kind={errorDetails.kind}
showExplanation={false}
dialogResizerRef={dialogResizerRef}
generateErrorInfo={generateErrorInfo}
/>
</Suspense>
</ErrorOverlayLayout>
)
}
case 'dynamic-metadata': {
switch (errorDetails.variant) {
case 'runtime':
......
......@@ -140,6 +140,25 @@ export function FixCardZapIcon() {
)
}
export function FixCardRouteIcon() {
return (
<svg
width="16"
height="16"
viewBox="0 0 16 16"
fill="none"
xmlns="http://www.w3.org/2000/svg"
>
<path
fill="currentColor"
fillRule="evenodd"
clipRule="evenodd"
d="M7.53.72 7 .19 5.94 1.25l.53.53.22.22H3.37a3.38 3.38 0 0 0 0 6.75h9.25a1.88 1.88 0 0 1 0 3.75H4.9a2.5 2.5 0 1 0 0 1.5h7.74a3.37 3.37 0 1 0 0-6.75H3.37a1.88 1.88 0 0 1 0-3.75H6.7l-.22.22-.53.53L7 5.31l.53-.53 1.32-1.32a1 1 0 0 0 0-1.42zM2.5 14.25a1 1 0 1 0 0-2 1 1 0 0 0 0 2m12-11.5a1 1 0 1 1-2 0 1 1 0 0 1 2 0m1.5 0a2.5 2.5 0 1 1-5 0 2.5 2.5 0 0 1 5 0"
/>
</svg>
)
}
export function FixCardTimerIcon() {
return (
<svg
......
export function throwMissingGspErrorInStaticRoute(page: string) {
throw new Error(
`Page "${page}" is missing \`generateStaticParams()\` which is currently not supported with \`ensureStatic = "navigation"\`. See more info here: https://nextjs.org/docs/messages/generate-static-params`
`Page "${page}": \`ensureStatic = "navigation"\` requires an exported \`generateStaticParams()\` function.\nLearn more: https://nextjs.org/docs/messages/generate-static-params#with-ensurestatic`
)
}
......@@ -9,6 +9,6 @@ export function throwIncompleteStaticParamsErrorInStaticRoute(
missingParamNames: string[]
) {
throw new Error(
`Page "${page}" returned incomplete params from \`generateStaticParams()\`. This is currently unsupported with \`ensureStatic = "navigation"\`. Every params object must include all dynamic route parameters. Missing: ${missingParamNames.map((name) => `"${name}"`).join(', ')}. See more info here: https://nextjs.org/docs/messages/generate-static-params`
`Page "${page}": \`generateStaticParams()\` returned incomplete params. Routes using \`ensureStatic = "navigation"\` must return every dynamic route parameter. Missing: ${missingParamNames.map((name) => `"${name}"`).join(', ')}.\nLearn more: https://nextjs.org/docs/messages/generate-static-params#with-ensurestatic`
)
}
......@@ -1408,15 +1408,9 @@ export function registerHeadAndReportingTests(
expectInsightsToMatchPattern(insights, errorPattern.dev)
expect(insights).toMatchInlineSnapshot(`
{
"description": "Route "/shells/ensure-static/navigation/session-data-without-suspense": Next.js encountered runtime data on a route that must be fully static.
\`cookies()\`, \`headers()\`, \`params\`, or \`searchParams\` prevent the route from being prerendered.
Ways to fix this:
- [static-params] For \`params\`: specify a static set of params to be prerendered using \`generateStaticParams\`
- [client] For \`searchParams\`: read on the client with \`useSearchParams()\`",
"description": "Next.js encountered runtime data on a route that must be fully static.",
"environmentLabel": "Server",
"label": "Console Error",
"label": "Static Route",
"source": "app/shells/(default)/ensure-static/_base/session-data-without-suspense/page.base.tsx (25:16) @ Cookies
> 25 | await cookies()
| ^",
......@@ -1439,11 +1433,14 @@ export function registerHeadAndReportingTests(
expect(error).toMatchInlineSnapshot(`
"Error: Route "/shells/ensure-static/navigation/session-data-without-suspense": Next.js encountered uncached or runtime data on a route that must be fully static.
\`fetch(...)\`, \`cookies()\`, \`headers()\`, \`params\`, \`searchParams\`, or \`connection()\` prevents the route from being prerendered.
This route is configured to be fully static, but uncached or runtime data prevents it from being fully prerendered.
Ways to fix this:
- [cache] For uncached data (\`fetch\`, database calls): cache the access with \`"use cache"\` (does not apply to \`connection()\`)
- [remove] Remove the data access
- Only applies to \`searchParams\`: read them on the client with \`useSearchParams()\`
Learn more: https://nextjs.org/docs/messages/static-route-dynamic
at main (<anonymous>)
at body (<anonymous>)
at html (<anonymous>)
......
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