How to Fix: Empty ISR docs page for pages router in v15

The ISR documentation page for the Pages Router in Next.js v15 can appear completely empty when the docs site links to a route that no longer resolves correctly in the current documentation tree. In practice, this is usually a documentation routing mismatch between canary/versioned docs content, the Pages Router section, and the page generation logic used by the Next.js docs site.

Problem Overview

The reported issue affects the documentation page for Incremental Static Regeneration (ISR) under the Pages Router in v15/canary docs. Instead of rendering the expected content, the page loads as blank or empty.

This is not an application-runtime ISR bug inside a user project. It is a docs-site content rendering bug. The failing page is the documentation route linked from the ISR docs page, and the root of the issue is usually one of the following:

• The page path exists in navigation but the underlying MDX/content source is missing or moved.
• The docs build expects a versioned content file that is not present for canary/v15.
• The docs route is generated, but the content loader returns empty data or fails silently.
• A redirect or route mapping for Pages Router docs points to a stale slug.

Understanding the Root Cause

Technically, this happens because the docs application is still able to resolve the URL structure, but it fails to resolve valid page content for that route. In a modern Next.js docs site, content pages are commonly assembled from MDX files, frontmatter metadata, route manifests, and version-specific navigation trees. If any of those layers become inconsistent, the UI may render an empty shell.

For this specific issue, the likely failure pattern is:

1. A navigation entry or direct link points to the ISR page under /docs/canary/pages/building-your-application/data-fetching/incremental-static-regeneration.
2. The docs router matches the route successfully.
3. The page component attempts to fetch or import the corresponding content source.
4. The content source is missing, renamed, excluded from the canary build, or not registered in the Pages Router docs manifest.
5. The rendering layer receives null, undefined, or structurally incomplete content data and produces a blank page.

In other words, the bug is typically not in ISR itself. It is in the documentation content pipeline or the route-to-content mapping.

Common technical causes include:

• Missing MDX file for the canary/versioned route.
• Broken slug registration after a docs reorganization.
• Conditional rendering without fallback UI, causing an empty result when content is absent.
• Incorrect redirect configuration between App Router and Pages Router documentation sections.
• Build-time content manifest drift where navigation metadata references a file that the build no longer includes.

Step-by-Step Solution

If you are fixing this inside the Next.js docs repository or a similar docs platform, the safest approach is to verify the route mapping, content source, and fallback handling in order.

1. Confirm the route is expected to exist

Search the docs navigation, versioned content folders, and route definitions for the ISR slug.

incremental-static-regeneration

Check whether the route is intentionally valid for:

• canary
• v15
• Pages Router

If the docs were moved or deprecated, the link should redirect rather than render an empty page.

2. Verify the content file exists

Inspect the docs content directory and confirm that the ISR page file is present in the correct versioned location.

# example search patterns inside the docs repo
find . -iname "*incremental-static-regeneration*"
grep -R "incremental-static-regeneration" .

You are looking for a valid MDX or content source file that matches the route. If the file was renamed or moved, update the slug mapping or navigation entry.

3. Check route-to-content resolution logic

If your docs site loads content dynamically, inspect the page loader function. A common bug is assuming content always exists.

export async function getDocBySlug(slug) {
  const doc = await docsIndex.find((entry) => entry.slug === slug)

  if (!doc) {
    throw new Error(`Missing doc for slug: ${slug}`)
  }

  return doc
}

This is better than silently returning nothing. If the current implementation returns an empty value, the UI may mount without content and appear blank.

4. Add defensive fallback rendering

The page component should not render an empty shell when content resolution fails. Add an explicit fallback or 404 behavior.

export default async function DocPage({ params }) {
  const doc = await getDocBySlug(params.slug)

  if (!doc) {
    notFound()
  }

  return <DocsRenderer doc={doc} />
}

If this is a Pages Router-based docs site, the equivalent pattern applies in getStaticProps:

export async function getStaticProps({ params }) {
  const doc = await getDocBySlug(params.slug)

  if (!doc) {
    return {
      notFound: true,
    }
  }

  return {
    props: { doc },
  }
}

This ensures users see a valid 404 instead of a blank page.

5. Fix stale navigation or redirects

If the page was moved to a different docs section, update internal links and redirects so the old route resolves cleanly.

module.exports = {
  async redirects() {
    return [
      {
        source: '/docs/canary/pages/building-your-application/data-fetching/incremental-static-regeneration',
        destination: '/docs/pages/building-your-application/data-fetching/incremental-static-regeneration',
        permanent: false,
      },
    ]
  },
}

Use this only if the intended fix is a route move. If the page should exist at the original path, restore the content instead.

6. Validate version-specific docs manifests

If your docs site builds a manifest for sidebar navigation or content lookup, ensure the page is registered in the correct version.

{
  "title": "Incremental Static Regeneration",
  "slug": "/docs/canary/pages/building-your-application/data-fetching/incremental-static-regeneration",
  "section": "data-fetching"
}

If the page exists on disk but not in the generated manifest, the route may resolve incompletely.

7. Test locally before publishing

Run the docs site locally and verify:

• The route renders actual content.
• The sidebar entry points to the correct slug.
• Direct access does not produce a blank page.
• Missing content now returns a 404 or visible error state.

pnpm dev
# or
npm run dev

Then open the affected route in the browser and confirm the final behavior.

Common Edge Cases

• Canary-only breakage: Stable docs may work while canary docs fail because the new version branch is missing the content file.
• Sidebar works, direct route fails: A client-side navigation cache may mask route issues that only appear on hard refresh.
• Content file exists, but frontmatter is invalid: Malformed metadata can cause the doc parser to skip rendering.
• Slug collision: Another page with the same generated slug can override or confuse resolution logic.
• Silent import failure: Dynamic imports for MDX content may fail during build or runtime without an obvious user-facing error.
• Wrong router section: Content may exist for the App Router docs but not for the Pages Router path, leaving one route empty.

A particularly important edge case here is a partial documentation migration. If the ISR page was updated for one docs architecture but not the other, the navigation may still expose a path whose content source no longer exists.

FAQ

Why does the page load instead of showing a 404?

Because the route matcher is probably valid, but the content loader returns empty data. Without explicit fallback handling such as notFound() or notFound: true, the page component can render a blank layout.

Is this a bug in Incremental Static Regeneration itself?

No. This issue is about the documentation page rendering, not the ISR feature in user applications. The failure is typically in docs routing, MDX resolution, or versioned content registration.

What is the best permanent fix?

The best fix is to restore a correct route-to-content mapping and add a defensive fallback so missing docs never render as an empty page again. If the route is deprecated, replace it with a proper redirect.

For maintainers, the most robust resolution combines three changes: restore or re-register the ISR content file, verify the canary/v15 Pages Router slug, and make the docs renderer fail with a visible 404 or error state instead of silently rendering nothing.