Next.js encountered runtime data during prerendering or a navigation

During prerendering, cookies(), headers(), params, or searchParams was read outside of <Suspense>. With Cache Components 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.

Uncached data accesses (fetch(), database calls, await connection()) have different fixes. See Next.js encountered uncached data during prerendering.

This error can also appear during a client-side navigation when the data access sits inside a <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. See Choosing where to place the boundary.

Ways to fix this

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> boundary lets the static shell ship instantly while the dynamic region streams in once the request value resolves.

Patterns

Wrap the existing component in place

Keep the component that reads the runtime API intact and add a <Suspense> boundary around its usage in the parent.

import { Suspense } from 'react'
import { UserHeader } from './user-header'
import { HeaderSkeleton } from './header-skeleton'

export default function Page() {
  return (
    <DashboardShell>
      <Suspense fallback={<HeaderSkeleton />}>
        <UserHeader />
      </Suspense>
      <CachedStats />
    </DashboardShell>
  )
}

Learn more: Streaming.

Push the access down to the leaf

When the value is read at the top of the tree but only consumed by a small piece of UI, move the read down. The parent stays prerenderable and only the leaf needs a boundary.

import { Suspense } from 'react'

export default function Page() {
  return (
    <DashboardShell>
      <Suspense fallback={<HeaderSkeleton />}>
        <UserHeader />
      </Suspense>
      <CachedStats />
    </DashboardShell>
  )
}

import { cookies } from 'next/headers'

export async function UserHeader() {
  const session = (await cookies()).get('session')
  return <header>Signed in as {session?.value}</header>
}

Learn more: Streaming.

Pass searchParams without awaiting

When the consumer is a child component, pass the promise down instead of awaiting it at the top. The child wraps its own consumption in <Suspense>, which keeps the parent prerenderable.

import { Suspense } from 'react'
import { Results } from './results'

export default function Page({ searchParams }) {
  return (
    <DashboardShell>
      <DashboardHeader />
      <Suspense fallback={<ResultsSkeleton />}>
        <Results searchParams={searchParams} />
      </Suspense>
    </DashboardShell>
  )
}

export async function Results({ searchParams }) {
  const { q } = await searchParams
  const widgets = await searchWidgets(q)
  return <WidgetList widgets={widgets} />
}

Learn more: searchParams.

Forward searchParams as a promise chain

A variant of the previous pattern when you want to derive a value without awaiting at the top. Treat searchParams as a promise and .then() it to project the shape the child needs.

export default function Page({ searchParams }) {
  const coords = searchParams.then((sp) => ({
    lat: Number(sp.lat),
    lng: Number(sp.lng),
  }))
  return <Map coords={coords} />
}

Learn more: searchParams.

Use loading.js for the whole segment

When every component in the segment reads the same request value and there's nothing static to render above it, a loading.js file in the segment is the shorthand. Next.js wraps {children} of the layout in <Suspense> automatically.

export default function Loading() {
  return <DashboardSkeleton />
}

Good to know: A loading.js file wraps the segment's {children} in one Suspense boundary. Parent layouts above it still prerender, but everything inside the segment sits behind the fallback. If page-level content could be prerendered (a static intro, a known title), use explicit <Suspense> boundaries inside page.js around only the dynamic parts.

Learn more: loading.js and instant loading states.

Trade-off

The shell ships immediately, but the user sees a loading state for the streamed region on every request. Design the fallback so it approximates the final layout. A generic spinner causes a layout shift when content arrives. See minimizing layout shift.

Choosing where to place the boundary

The location of the boundary controls what the user sees during the navigation:

• A high boundary (around the whole page) gives one loading state for everything. Less work to set up, but the user loses context about where they were going.
• A low boundary (around the specific component that reads the runtime API) keeps surrounding content visible and only shows a fallback for the per-request part. Preferred when the surrounding shell has cached content.

A useful rule: push the boundary as low as possible while keeping the fallback meaningful. The cached content above the boundary becomes part of the static shell on navigation. Wrapping individual pieces or wrapping the whole page in one boundary stream the same way, but a lower boundary keeps more prerendered content visible during the navigation. See Maximizing the static shell for the canonical pattern.

Gotchas

• The fallback must be deterministic. Calling Math.random() or Date.now() inside the fallback raises a separate Cache Components error during prerendering.
• Do not pass {children} through in the fallback. Child pages may include dynamic reads (for example, /_not-found calling cookies() or headers()) that propagate into what should be a static fallback. Render a placeholder that doesn't include {children}.
• If the failing route is /_not-found and you don't have a not-found.tsx file, the read is in the root layout. /_not-found is a real prerendered route that inherits the root layout, so a cookies() or headers() read there fails on the synthetic route too. Run next build --debug-prerender to confirm the originating file, and fix it at the layout, not by adding a not-found.tsx.
• Boundary placement affects client navigations between sibling routes differently than initial page loads. Validation surfaces this in the dev server and at build time. See Ensuring instant navigations for the full model.
• The function returned by cookies() and headers() is async. Make sure the component reading them is async too, and await the call.
• The params and searchParams props are also async promises. Treat them like any other awaited value when deciding where the boundary goes.
• Root-element attributes (<html lang>, <html dir>, <html data-theme>) can't be wrapped in <Suspense>. You can't suspend the document root, and a boundary inside <html> still leaves the attribute itself server-cookie-dependent. Move the read to a pre-paint client script per Preventing flash before hydration and add suppressHydrationWarning on <html> so React doesn't flag the script's mutation as a mismatch.

Allow blocking route

Choose this fix when the route renders per-request and there's no useful static shell. Setting instant to false exempts the segment from instant-navigation validation. The page renders on every request and the navigation blocks until that render completes.

Patterns

Opt the page out

Add the export to the page that triggered the error. Only that route blocks.

export const instant = false

export default async function Page() {
  const session = (await cookies()).get('session')
  return <Dashboard session={session?.value} />
}

Learn more: Ensuring instant navigations.

Opt the layout out

When the shared layout itself can't ship instantly (it reads cookies() or headers() of its own), set instant to false on the layout. This allows that layout segment to block while descendant segments remain independently validated.

export const instant = false

export default function DashboardLayout({ children }) {
  return <DashboardShell>{children}</DashboardShell>
}

Learn more: Route segment instant config.

Use either pattern when:

• The route needs request-time data high in the tree to decide what to render (for example auth, tenant, or other gating in a layout), so there is no meaningful static shell worth showing first.
• You're migrating a route incrementally and want to defer the lifetime decision without changing how the page renders today.

Don't use this to dismiss the error. Choose Wrap in or move into Suspense when feasible.

Trade-off

Navigations to this route are not instant. The user waits for the full server render before any HTML arrives. Use this only when that latency is necessary for the route to function.

Gotchas

• Setting 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. The route still prerenders if it can. It only disables instant-navigation validation for the route.

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> boundary placed around the whole page body can pass validation with an empty shell, which defeats the point of an instant navigation.

In next dev, the error overlay points at the failing component with file paths and line numbers. When working from a build instead, the default next build output is more abbreviated. Run next build --debug-prerender for full user-frame stack traces and next build --debug-build-paths /dashboard /settings to iterate on specific routes.

Don't want this validation?

Instant-navigation validation runs by default in Cache Components apps and is what surfaces this error.

• One segment: add export const instant = false to the page or layout file. This opts out the segment itself. Child segments are still validated during client navigations.
• Entire app: set experimental.instantInsights.validationLevel to 'manual-warning' in next.config. This limits validation to segments that explicitly export instant.

See Ensuring instant navigations for the full model.

Related Insights

• Uncached data during prerendering
• URL data in a Client Component outside of Suspense
• Runtime data in generateMetadata()
• Uncached data in generateMetadata()
• Runtime data in generateViewport()
• Uncached data in generateViewport()
• Math.random() while prerendering
• Math.random() in a Client Component
• Date.now() while prerendering
• Date.now() in a Client Component
• Crypto APIs while prerendering
• Crypto APIs in a Client Component
• Dynamic data during prefetching
• URL data outside of Suspense
• Unrendered segment