next.js: [dynamicIO] Build error when using `Date.now` in a client component within `use cache`

Link to the code that reproduces this issue

https://github.com/a463/next-date-now-cache-error

To Reproduce

  1. Clone the repo
  2. Run npm run build

Current vs. Expected behavior

Currently the build throws:

Error: Route "/" used `Date.now()` instead of using `performance` or without explicitly calling `await connection()` beforehand. See more info here: https://nextjs.org/docs/messages/next-prerender-current-time
    at a (.next/server/app/page.js:1:3890)
Error occurred prerendering page "/". Read more: https://nextjs.org/docs/messages/prerender-error
Export encountered an error on /page: /, exiting the build.
 ⨯ Next.js build worker exited with code: 1 and signal: null

The reproduction is very minimal, it has a single route with a use cache directive, it makes a request to a placeholder API and then renders a client component. The client components calls Date.now(), the error is thrown despite the call being within a use cache

Provide environment information

Operating System:
  Platform: linux
  Arch: x64
  Version: #1 SMP Thu Oct 5 21:02:42 UTC 2023
  Available memory (MB): 32768
  Available CPU cores: 16
Binaries:
  Node: 22.13.1
  npm: 10.9.2
  Yarn: 1.22.22
  pnpm: 9.12.1
Relevant Packages:
  next: 15.2.0-canary.76 // Latest available version is detected (15.2.0-canary.76).
  eslint-config-next: N/A
  react: 19.0.0
  react-dom: 19.0.0
  typescript: 5.7.3
Next.js Config:
  output: N/A

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

dynamicIO

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

next build (local), next dev (local)

Additional context

No response

About this issue

  • Original URL
  • State: open
  • Created 2 years ago
  • Reactions: 3
  • Comments: 25 (23 by maintainers)

Most upvoted comments

Hi folks, we haven’t really “released” dynamicIO yet and as such we haven’t published a comprehensive guide to understanding how to think about what Next.js expects when you turn it on. It’s also changed a bit since we teased this feature at Next.js conf last year.

I’ll do a current summary here just to address what is wrong with the repro. We will have real docs when we announce this feature as something we invite folks to try

Server Components are cacheable and "use cache" tells Next.js to do exactly that. This is what allows us to know that things that usually are meant to be done per-request can be done once ahead of time and reused. The output of a Server Component render is a tree of client components. Sometimes these are just DOM components like <div> but they can also be components you wrote like the Content component in the example.

Even if you use "use cache" to cache the result of the Server Component tree that doesn’t perpetually cache the state of the Client Components it renders. First, that would be very hard to implement, but it is also a little confusing because if you navigated to a new page via link (no SSR) we would start rendering the new Client Components on the page but somehow load up cached values for things like new Date(). It would break your intuition about the Client Components running in your browser when they mount.

So effectively Client Components are the domain of the browser and are always “dynamic”.

So what about SSR. Well if it turns out your client component doesn’t do anything dynamic we can play a little trick and render it ahead of time because we know it doesn’t actually do anything dynamic. If it does we have to exclude the component from the prerender. If it doesn’t we can include it.

So basically you should think that doing dynamic stuff in client components is perfectly fine to do. But then why does this repro error? Well we are heading towards releasing not just dynamicIO but also partial prerendering. The features are designed for each other. And what this means is that Next.js will expect to be able to produce a partial (or complete) static shell for every route at build time. The repro doesn’t have any Suspense boundaries so when we attempt to prerender the HTML and hit that new Date() in a client component there is no fallback UI to use. We consider this an error and expect you to rectify it.

It’s possible that the solution is to move the dynamic stuff out of the render pathway (into event handlers, or effects) though you aren’t really in control of that directly for 3rd party libs. Alternatively you can wrap the dynamic component in a Suspense boundary that tells Next.js what to prerender in it’s place.

For the most popular libraries we expect that there will be a period of upstreaming where we identify incompatibilities and submit patches to adjust them. We’ve already done that with motion.dev and react-query and expect that there will be more as we approach stability with this feature. Often the use of Math.random() or new Date() in a Client Component is unecessary to what is trying to be achieved and you can accomplish the same thing with using these APIs. But of course this needs to be evaluated on a case by case basis.

So I’ve found a bug in how we identify the offending dynamic reason. It’s possible the date isn’t the thing causing the problem but our reporting is incorrectly stating this as the reason. I’ll land a fix in the next couple days and report back. Then we can see if the deployed case that is inconsistent is the cause.

The reason you aren’t getting a line is probably that the stack is being ignore listed because of node_modules. Going to see what we can do about this because we need to be able to give at least some way to locate the offending code.

Thanks so much for digging in.

The viewport issue is stemming from interactions between sync IO in client components + the microtasky nature of the RSC response being processed during SSR. This PR should address it: https://github.com/vercel/next.js/pull/80125

There is another issue if you are using generateMetadata and have something dynamic that depends on request data like await cookies(). Not sure if you have that in your project but if you do then there is another fix we need to land which isn’t PR’d yet. Basically if the metadata throws during prerender and you don’t have a Suspense around your Page component then there will be no shell produced but it won’t have any specific dynamic reason.

There was an oversight when metadata was made streaming where you can sometimes still block the whole page during perendering.

Thank you for you reply. I am not sure I understand what the purpose of lifting the Date.now() call to the parent component is. In my reproduction, the <Content> component that makes the call is already within a use cache boundary, see https://github.com/a463/next-date-now-cache-error/blob/main/src/app/page.tsx#L6-L11. This error is making it impossible to use Date.now in client components with static rendering.

For my second point, I get why explicit intent is needed in server components, but it’s unclear why Next requires intent for Date.now in client components. In my opinion, it should be fine to assume “static”, because those components are hydrated in the browser, so the dev is expecting an outdated/different value from the server. The docs say:

Note that Server Side Rendering timestamps in a Client Component is also considered ambiguous so to implement this properly Next.js needs you to only read the time in the browser, for instance by using useLayoutEffect() or useEffect().

Which is not always possible, for instance, if a third-party library is executing it.