I want to understand why setting a placeholder in generateStaticParams works

[laurenskling]

https://nextjs.org/docs/messages/empty-generate-static-params#option-2-use-a-placeholder-param, this solution absolutely solves all my troubled with cacheComponents, but it states it should be avoided. Found this at #85807 (comment)

So I want to ask; why does this work at the first place?

With this, I can skip the <Suspsense> around my { slug } = await params (got only a [...slug] segment in my sites, it renders all CMS pages of all types, so I need it always).

With this, I can see .next/server/app fill up with .html and .meta files for all my pages. So this is actually what I want. All routes that get hit are hard cached when visited. Perfect.

So why do I need this placeholder "hack" in the first place? Why doesn't it work without this?

And I don't understand the downsides. "minimal build-time validation and increases the risk of runtime errors for actual parameter values". Validation of what? What actual parameter values, slugs? Without a generateStaticParams (I don't want to prebuild my entire site on build, I want it to cache lazy) I also risk runtime slugs right?

[icyJoseph]

Pre Cache Components, with an empty array from generateStaticParams, popular trick to do ISR, there could be a headers or cookie call deep in your tree, only invoked with certain parameters combinations, which would lead to an error at runtime when the page is ISR'd, because ISR happens in isolation from any request - it would be a bad idea to ISR anyone's data from cookies anyway.

You'd then have to provide a set of params that hit the headers or cookie call during build time, which would label the page as dynamic, but then we lost the ISR, we can't serve these from a CDN anymore.

In a Cache Components, pages can both contain static and dynamic parts, but how does the prerendering step know what's being used in a given page, and that a static shell can be generated? Again, you provide a set of params that Next.js uses to try to generate a static shell, which can be placed on a CDN, while still being able to serve UI that depends on cookies/headers etc.

When you by pass with a placeholder item, the build time is unable to discover any API access that would prevent creating a static shell. Of course, even if you provide one parameter, you can still have branches (like the placeholder one) that error during prerendering runtime, but the frameworks main intention is to validate that at least one value can complete.

Moreover, we have an upcoming feature called partialFallbacks, which allows you to prerender a subset of param pages, and then at runtime, accessing a "new" param, serves a common static shell, if available, and upgrades this "new" param combination in the background, to serve a static shell (in the best case scenario), so that a future visitor sees the content immediately, not the common static shell. That sounds like something that fits your use case.

[icyJoseph]

Can you add more info, like, what flags are involved here, partialFallbacks plays a role too right?

I'd want to see repository where this is demonstrated. I was just trying out cacheHandler, and cacheHandlers, both setup, and serving from disk etc

For the most part my cacheHandler seems to work fine, and I can save to .next/my-isr. I did run into other a couple of other issues... I should probably try with one of the custom handlers written by the community, and see from there...

[apostolos]

I finally have it reduced! You just need to set cacheComponents: true, which now also enables partialFallbacks. No custom cache handler is needed.

Create a route with a param and at least one generateStaticParams sample.

Build the app. Then to simulate what would happen with a custom cache handler, just delete the prerender cache. The parts that would be missing if you use an external cache and not pre-populate it (<- the thing that was missing from our deployment):

# Delete prerender cache (html for APP_PAGE, body for APP_ROUTE + metadata for both + RSC payloads)
find .next/server/app -type f \( -name "*.meta" -o -name "*.rsc" -o -name "*.body" -o -name "*.html" \) -delete

Start the app and visit the dynamic route (via a full page navigation). You should get the error.

From the community, I'm only aware of @neshca/cache-handler, which I don't think is up-to-date with the latest canaries, but at least now they do have an extra step specifically for populating the external cache:

I don't think that was there on their first releases, so I guess they discovered the problem on their own.

[icyJoseph]

Aha wait, you didn't have cacheComponents on, and was trying out partialFallbacks? Mmm interesting - I know some use a custom handler with memory set to zero, and then control where ISR writes.

Good that it worked though!

[apostolos]

No, we did have it enabled. I just confirmed that this was the only flag needed to reproduce the error. It started when the default for partialFallbacks was changed to true. We didn't have partialFallbacks enabled before.

This is all secondary though. The primary problem is that the custom cache handler is skipped during build. If that was not the case, the problem would never have manifested.

I think that I can understand why Next.js is doing this. It must need the files in order to build all the manifests, etc. I wonder if it could be possible to dual write while building: use the file-system-cache for its own purposes and at the same time call set() on the custom cache handler. That way, the extra step of populating the external cache would not be needed.

[jameh0266-boop]

This usually isn’t a single Next.js bug—it’s often related to caching, build behavior, or environment differences.

A good first step is to clear your .next cache and reinstall dependencies, since stale builds are a common cause. Also try running without Turbopack (next dev) because some users have reported inconsistent behavior in newer setups, as discussed in similar threads on the official discussions page: https://github.com/vercel/next.js/discussions

It’s also worth comparing dev vs production builds, since differences there often point to SSR/client mismatches or caching issues. The official docs on configuration and debugging can help guide this: https://nextjs.org/docs

If the issue still persists, check open issues here: https://github.com/vercel/next.js/issuesissues
— many recent problems are tied to evolving tooling and caching behavior in newer versions.

[Johnymacclen]

I think the key distinction is that the placeholder is not what makes the route “lazy cached.” It mainly gives Cache Components a concrete parameter value to use during the build-time prerender/validation pass.

With cacheComponents, Next.js needs at least one generateStaticParams() result because it uses that value to actually execute the route during the build. An empty array gives it no concrete route to test, so it cannot verify whether the route can be prerendered safely. In particular, it is checking for things such as cookies(), headers(), searchParams, or other runtime/uncached data being accessed outside an appropriate Suspense/cache boundary. The current docs explain this requirement here:
https://nextjs.org/docs/messages/empty-generate-static-params

The important part is that generateStaticParams() does not mean “all these routes must be generated at build time.” With Cache Components, the runtime behavior is still compatible with your use case: pages with parameters that weren't known at build time can be rendered on their first request and then persisted/cached. The dynamic-routes documentation explicitly describes this behavior:
https://nextjs.org/docs/app/api-reference/file-conventions/dynamic-routesassi

So in your case, something like:

export async function generateStaticParams() {
  return [{ slug: ['__placeholder__'] }]
}

is effectively giving the compiler a representative route so it can perform its prerender validation. The actual CMS slugs can still be discovered at runtime.

The downside of the placeholder is specifically the quality of that validation. Next.js only executes the code paths that are reached with the placeholder value. If your application behaves differently for different real slugs—for example, one type of CMS page calls cookies() or headers(), while another doesn't—the build only validated the placeholder's path through that logic. A real slug could therefore expose a runtime error that the build never saw.

That's what the documentation means by:

“minimal build-time validation and increases the risk of runtime errors for actual parameter values”

So I wouldn't interpret the warning as “this will break lazy caching.” It's more like: you're intentionally giving up comprehensive build-time coverage in exchange for not having to know every CMS route at build time.

And you're right about the runtime-slug argument: without generateStaticParams, you already have runtime parameters and therefore runtime failure possibilities. The difference is that without it, Cache Components cannot establish a concrete parameter value during prerendering at all, so it requires the params access to be handled as runtime data (hence the Suspense requirement). With the placeholder, Next gets one concrete value and can prove that that particular execution is prerenderable.

This also explains the behavior you're seeing with .next/server/app: the placeholder isn't necessarily causing every CMS page to be generated at build time. Rather, it changes the route's prerendering/validation model, while previously unknown params can still be rendered and cached when requested.

There is also a useful related discussion in the Next.js repo showing that returning at least one value can change Cache Components behavior in ways that feel somewhat surprising:
#85239

I'd therefore describe the placeholder as a workaround for the current build-time validation requirement, not as a magic switch for lazy caching. If your CMS route is intentionally “any slug can exist,” and you have tests/validation around the different CMS page types, the trade-off can be reasonable. But I would keep an eye on this behavior as Cache Components evolves, because relying on the placeholder specifically to bypass the empty-params restriction is not the same thing as Next.js officially guaranteeing that placeholder values are semantically meaningful.