Issue Station
Sign In
Tools hereToolbox

nextjs - ✅(Solved) Fix Inconsistent behavior for pages with generateStaticParams [1 pull requests, 2 comments, 3 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
vercel/next.js#84801•Fetched 2026-04-08 02:18:17
View on GitHub
Comments
2
Participants
3
Timeline
9
Reactions
0
Author
mastojmastoj
Participants
github-actions[bot]github-actions[bot]mastojmastojwyattjohwyattjoh
Timeline (top)
commented ×2closed ×1cross-referenced ×1issue_type_added ×1

Fix Action

Fixed

PR fix notes

PR #85135: feat(cache-components): require non-empty generateStaticParams for validation

Description (problem / solution / changelog)

What?

This PR adds build-time validation that requires generateStaticParams to return at least one result when Cache Components (experimental cacheComponents feature) is enabled.

Why?

Previously, users could return an empty array ([]) from generateStaticParams to indicate a route should be treated statically without providing specific parameter values. This pattern has a critical issue with Cache Components:

The Problem:

  • With Cache Components enabled, accessing params is treated as a dynamic API usage
  • When generateStaticParams returns empty results, Next.js cannot perform build-time validation to detect if the route accesses other dynamic APIs (like await cookies(), await headers(), or await searchParams)
  • This means users could successfully build routes that would fail at runtime with dynamic API errors

The Solution:

  • By requiring at least one parameter value, we can execute the route during build time with real params
  • This allows us to validate that the route doesn't make additional dynamic API calls that would cause runtime failures
  • Build-time validation catches configuration errors early, before deployment

How?

  • Modified buildAppStaticPaths in packages/next/src/build/static-paths/app.ts to check if PPR is enabled and throw error when generateStaticParams returns empty array with Cache Components enabled
  • Added comprehensive error documentation at errors/empty-generate-static-params.mdx with migration options

Migration paths provided in error documentation:

  1. Return at least one real param (recommended)
  2. Use placeholder params (not recommended, bypasses validation)

The breaking change is acceptable because cacheComponents is still experimental and only available in canary releases.

Related

Changed files

  • errors/empty-generate-static-params.mdx (added, +69/-0)
  • packages/next/errors.json (modified, +2/-1)
  • packages/next/src/build/static-paths/app.test.ts (modified, +72/-28)
  • packages/next/src/build/static-paths/app.ts (modified, +15/-3)
  • packages/next/src/shared/lib/errors/empty-generate-static-params-error.ts (added, +13/-0)
  • packages/next/src/shared/lib/errors/missing-default-parallel-route-error.ts (modified, +5/-7)
  • packages/next/src/shared/lib/errors/usage-error.ts (added, +10/-0)
  • test/e2e/app-dir/app-alias/src/app/typing/[slug]/page.tsx (modified, +1/-1)
  • test/e2e/app-dir/app-catch-all-optional/app/[lang]/[flags]/[[...rest]]/page.tsx (modified, +1/-1)
  • test/e2e/app-dir/not-found-with-pages-i18n/app/app-dir/[[...slug]]/page.tsx (modified, +1/-1)
  • test/e2e/app-dir/sub-shell-generation-middleware/app/rewrite/[slug]/page.tsx (modified, +1/-1)
  • test/e2e/app-dir/sub-shell-generation/app/[lang]/[slug]/page.tsx (modified, +1/-1)
  • test/production/app-dir/empty-generate-static-params/empty-generate-static-params.test.ts (modified, +33/-17)
  • test/production/standalone-mode/required-server-files/app/optional-catchall/[lang]/[flags]/[[...slug]]/page.jsx (modified, +1/-1)

Code Example

❯ npx --no-install next info

Operating System:
  Platform: darwin
  Arch: arm64
  Version: Darwin Kernel Version 24.6.0: Mon Jul 14 11:30:30 PDT 2025; root:xnu-11417.140.69~1/RELEASE_ARM64_T6020
  Available memory (MB): 65536
  Available CPU cores: 12
Binaries:
  Node: 20.18.1
  npm: 10.8.2
  Yarn: 1.22.22
  pnpm: 10.14.0
Relevant Packages:
  next: 16.0.0-canary.2 // Latest available version is detected (16.0.0-canary.2).
  eslint-config-next: 16.0.0-beta.0
  react: 19.1.0
  react-dom: 19.1.0
  typescript: 5.9.3
Next.js Config:
  output: N/A
RAW_BUFFERClick to expand / collapse

Link to the code that reproduces this issue

https://github.com/mastoj/next16-demo/tree/static-params-bug

To Reproduce

  1. Pull down the code
  2. Build app
  3. Start app
  4. Go to /anyslug and /wat/anyslug

Current vs. Expected behavior

The expected behavior is that /anyslug and /wat/anyslug behaves the same, but they aren't. For some reason the second box on the page is streamed in every time and not part of the render on /wat/anyslug. The only difference is that /[id] has defined some routes to in generateStaticParams (https://github.com/mastoj/next16-demo/blob/46a43943bb5bfc130bafc8f042d474b06a4ee788/app/%5Bid%5D/page.tsx#L8) while I return [] on /wat/[id].

Provide environment information

❯ npx --no-install next info

Operating System:
  Platform: darwin
  Arch: arm64
  Version: Darwin Kernel Version 24.6.0: Mon Jul 14 11:30:30 PDT 2025; root:xnu-11417.140.69~1/RELEASE_ARM64_T6020
  Available memory (MB): 65536
  Available CPU cores: 12
Binaries:
  Node: 20.18.1
  npm: 10.8.2
  Yarn: 1.22.22
  pnpm: 10.14.0
Relevant Packages:
  next: 16.0.0-canary.2 // Latest available version is detected (16.0.0-canary.2).
  eslint-config-next: 16.0.0-beta.0
  react: 19.1.0
  react-dom: 19.1.0
  typescript: 5.9.3
Next.js Config:
  output: N/A

Which area(s) are affected? (Select all that apply)

cacheComponents

Which stage(s) are affected? (Select all that apply)

next start (local), Vercel (Deployed)

Additional context

I have it deployed so you can check the different behavior here:

Not ok: https://next16-demo-git-static-params-bug-mastojs-projects.vercel.app/wat/anyslug Ok: https://next16-demo-git-static-params-bug-mastojs-projects.vercel.app/anyslug

Some more context how I would like it to work with the perspective of a fairly large ecom. Ideally we would be able to have a static shell that can always be served statically. This way any link from for example google would appear instantly with the static shell. When a page have the streamed in content should merge with the static shell so the second time someone visits from google the instant load contains both the shell we have for all pages together with the static content for that specific page. This way we would avoid flickering when coming from external sources combined with an instant first time load. From the looks now we have to render the whole thing the first time --> not instant. Considering a large portion of most ecommerce traffic is from sources like google to an internal page I do think this behavior is a huge win if it is possible to achieve.

extent analysis

TL;DR

  • The issue can be addressed by re-examining the usage of generateStaticParams in the affected routes to ensure consistent behavior between /anyslug and /wat/anyslug.

Guidance

  • Review the generateStaticParams function in app/[id]/page.tsx to understand how static parameters are being generated for the /[id] route.
  • Compare this implementation with the /wat/[id] route, where generateStaticParams returns an empty array, to identify potential discrepancies.
  • Consider modifying the generateStaticParams function for the /wat/[id] route to align with the expected behavior, potentially by generating static parameters similar to the /[id] route.
  • Test the application after making these changes to verify if the behavior of /anyslug and /wat/anyslug becomes consistent.

Example

  • No specific code example can be provided without modifying the existing codebase, but the focus should be on aligning the generateStaticParams function across the affected routes.

Notes

  • The desired behavior of having a static shell that can be served instantly, with streamed content merging seamlessly, suggests a need for careful handling of static site generation (SSG) and server-side rendering (SSR) or static HTML generation in Next.js.
  • The current implementation and the expected outcome may require deeper investigation into Next.js's routing and rendering mechanisms, especially regarding static parameters and their impact on page rendering.

Recommendation

  • Apply workaround: Modify the generateStaticParams function for the /wat/[id] route to generate static parameters consistently with the /[id] route, aiming to achieve the desired behavior of instant loading with merged static and dynamic content.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#agent setup#task chaining#parallel task#integration issue#index setup

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

nextjs - ✅(Solved) Fix Inconsistent behavior for pages with generateStaticParams [1 pull requests, 2 comments, 3 participants]