Next.js encountered dynamic data during prefetching

During a client-side navigation, a <Link prefetch={true}> navigated to a route that has not enabled Partial Prefetching. With Cache Components enabled, prefetch={true} is a legacy "full" prefetch that pulls down the route's dynamic data along with its App Shell. This will lead to slower, more expensive prefetches.

Routes that opt into Partial Prefetching skip the dynamic data at prefetch time, leaving you free to choose when it loads: at navigation via streaming, ahead of time via runtime prefetching, or not at all. The check fires at navigation time, not prefetch time, so existing apps that have recently enabled Cache Components are not flooded with warnings for every <Link prefetch={true}> on the page.

Ways to fix this

Opt into Partial Prefetching

Choose this fix when the target route has an App Shell with dynamic content below it. Opting into Partial Prefetching tells Next.js to prefetch only the App Shell and defer the dynamic data to navigation. Opt in per-route or app-wide, and from there layer on further prefetch optimizations.

Patterns

Per-route opt-in

Export prefetch from the page or layout of the route the link points at.

export const prefetch = 'partial'

export default function DashboardPage() {
  return <Dashboard />
}

App-wide opt-in

Set partialPrefetching to true in next.config to opt the whole app in.

module.exports = {
  partialPrefetching: true,
}

Keep prefetching the dynamic data

'partial' prefetches only the App Shell, which is the route's static and cached content. Uncached dynamic data is no longer prefetched. To keep prefetching content that came down with prefetch={true}, work through two steps.

1. Cache it with use cache. If the content doesn't depend on the URL, it gets included in the App Shell and that's enough.
2. If it depends on per-link runtime data (params, searchParams), it can't be included in the shared App Shell. With Partial Prefetching enabled, prefetch={true} opts the link into runtime prefetching, so the cached content is prefetched behind the runtime read.

import { Suspense } from 'react'

export const prefetch = 'partial'

async function getMetrics(range) {
  'use cache'
  const res = await fetch(`https://api.example.com/metrics?range=${range}`)
  return res.json()
}

async function Metrics({ searchParams }) {
  const { range } = await searchParams
  return <MetricsView metrics={await getMetrics(range)} />
}

export default function DashboardPage({ searchParams }) {
  return (
    <Suspense fallback={<Skeleton />}>
      <Metrics searchParams={searchParams} />
    </Suspense>
  )
}

Learn more: Adopting Partial Prefetching.

Trade-off

The route's dynamic data isn't included in the prefetch. The user sees the App Shell as soon as the link enters the viewport, and the dynamic content streams in after navigation. The dynamic content arrives later than it would with a full prefetch. How much later depends on how long the dynamic data takes to fetch.

Gotchas

• Partial Prefetching only works with Cache Components enabled.
• If the route doesn't have a clear App Shell (everything below the layout reads dynamic data), Partial Prefetching has nothing to prefetch and behaves the same as no prefetch. Move static content above the dynamic boundary first.

Use the default prefetch

Choose this fix when you set prefetch={true} to warm up a frequently-visited route and you can accept fetching the dynamic data on navigation. Remove the prop and the link uses the default prefetch strategy, which under Cache Components prefetches the App Shell (the route's static and cached content) and skips the dynamic data.

Patterns

Remove the prefetch prop

import Link from 'next/link'

export default function Nav() {
  return <Link href="/dashboard">Dashboard</Link>
}

Trade-off

The link no longer forces a full prefetch. The user gets the App Shell (static and cached content) when the link enters the viewport, and the dynamic data is fetched at navigation time. This is the default behavior under Cache Components.

Gotchas

• Removing prefetch={true} does not disable prefetching. It falls back to the default. To disable prefetching entirely, use prefetch={false}.
• See Adopting Partial Prefetching for the full table of what each <Link> prop downloads under each configuration.

Disable validation on this route

Choose this fix when you need the legacy full prefetch behavior and cannot adopt Partial Prefetching for the target route. Setting instant to false on the target route opts it out of instant-navigation validation.

Patterns

Opt the route out

Add the export to the page or layout file of the target route.

export const instant = false

export default function DashboardPage() {
  return <Dashboard />
}

Trade-off

The link continues to do a full prefetch, including dynamic data, and the warning is no longer reported.

Gotchas

• instant = false disables all instant-navigation checks for the route, not only this one. That includes Blocking-route and unrendered-segment warnings, and other Insights for the route.

Verifying the fix

After applying a fix, navigate to the route and confirm the insight no longer appears in the dev overlay and the page immediately paints meaningful UI, with any <Suspense> fallbacks covering only the regions that stream in. A <Suspense> boundary around the whole page body can pass validation with an empty shell, which defeats the point of an instant navigation.

Depending on your validation level, this may only surface in development.

Don't want this validation?

Instant-navigation validation runs by default in Cache Components apps and 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

• Runtime data during prerendering
• 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
• URL data outside of Suspense
• Unrendered segment