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

[a463]

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

[a463]

Not sure why client components are not allowed to access Date.now or Math.random, I have also seen similar errors like above when using motion's AnimatePresence and react-aria utilities.

I understand how intent is needed when calling these functions in server components. But I think in client components intent can be assumed, it should be fine to cache them in the server (if static page), as in the client they will be updated, and if there are issues we already have hydration errors.

That is already how dynamic SSR works, so libraries expect the usages of Date.now and Math.random to yield different results when hydration occurs in the client.

Sorry if I am missing something, but wouldn't that solve the issues many libraries are having with dynamicIO (also read some issues with Sentry)?

[samcx]

@a463 Thank you for submitting an issue!

With dynamicIO, we intend to figure out if dynamic behavior is intended or not by looking for IO. Date.now() is not technically IO, but it's ambiguous because usually, you intend for the time value to change every request. So with dynamicIO, we're requiring the user to be explicit about their intent with Date.now()

• https://nextjs.org/docs/messages/prerender-error

Interestingly, when I move the Date.now() to the Home page like this,

import { unstable_cacheLife as cacheLife } from "next/cache";
import { Content } from "./_content";
import { fetchPosts } from "./_posts";

export default async function Home() {
  "use cache";
  cacheLife("hours");

  const posts = await fetchPosts();
  const date = Date.now();

  return <Content posts={posts} date={date} />;
}

I get a possible next dev bug when I restart the next dev server. →

76569-dynamicIO-date-now [main] rmne && p dev

> next-cache-date-metadata-error@0.1.0 dev .../dynamicIO/76569-dynamicIO-date-now
> next dev --turbopack

   ▲ Next.js 15.2.2-canary.1 (Turbopack)
   - Local:        http://localhost:3000
   - Network:      http://192.168.68.66:3000
   - Experiments (use with caution):
     ✓ dynamicIO

 ✓ Starting...
 ✓ Ready in 568ms
 ✓ Compiled / in 359ms
Error: Route "/": A component accessed data, headers, params, searchParams, or a short-lived cache without a Suspense boundary nor a "use cache" above it. We don't have the exact line number added to error messages yet but you can see which component in the stack below. See more info: https://nextjs.org/docs/messages/next-prerender-missing-suspense
    at Lazy (<anonymous>)
    at Home [Server] (<anonymous>)
    at body (<anonymous>)
    at html (<anonymous>)
    at RootLayout [Server] (<anonymous>)
 GET / 200 in 1795ms
^C
76569-dynamicIO-date-now [main] p dev

> next-cache-date-metadata-error@0.1.0 dev .../dynamicIO/76569-dynamicIO-date-now
> next dev --turbopack

   ▲ Next.js 15.2.2-canary.1 (Turbopack)
   - Local:        http://localhost:3000
   - Network:      http://192.168.68.66:3000
   - Experiments (use with caution):
     ✓ dynamicIO

 ✓ Starting...
 ✓ Ready in 576ms
 ✓ Compiled / in 356ms
 GET / 200 in 1954ms

[a463]

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.

[followbl]

@samcx thanks for the reply on this one. I 100% understand what Next.js team is trying to do here, took me a little bit of time to wrap my head around this one. I do have to say, I think this change around new Date() is gonna drive people crazy.

I've upgraded our app to ppr with dynamicIO and despite the specific line error functionality not being in yet, it was fairly straightforward to migrate the application to take advantage of 'use cache'

one area, it has not be clear or helpful is around this date piece

@acme/www:build: Error: Route "/blog/[...slug]" used `new Date()` instead of using `performance` or without explicitly calling `await connection()` beforehand. See more info here: https://nextjs.org/docs/messages/next-prerender-current-time
@acme/www:build:     at e6.clientRateLimitContext (.next/server/chunks/ssr/_849972d5._.js:11:117995)
@acme/www:build:     at new e6 (.next/server/chunks/ssr/_849972d5._.js:11:117896)
@acme/www:build:     at new fz (.next/server/chunks/ssr/_849972d5._.js:11:141491)
@acme/www:build:     at 660722 (.next/server/chunks/ssr/_849972d5._.js:11:168925)
@acme/www:build:     at instantiateModule (.next/server/chunks/ssr/[turbopack]_runtime.js:601:23)
@acme/www:build:     at getOrInstantiateModuleFromParent (.next/server/chunks/ssr/[turbopack]_runtime.js:658:12)
@acme/www:build:     at esmImport (.next/server/chunks/ssr/[turbopack]_runtime.js:132:20)
@acme/www:build:     at 355909 (.next/server/chunks/ssr/_fe7eaf5f._.js:1:16263)
@acme/www:build: Error occurred prerendering page "/blog/123". Read more: https://nextjs.org/docs/messages/prerender-error

I'm non deterministically getting this error sometimes, which is more annoying. The build will complete and fail about 50% of the time. And the build will fully pass on the Vercel servers when I push up for a preview and production build.

this error leads back to new Date being used in analytics dependencies

I put together a configuration repro (only for demo of what's happening)

https://github.com/followbl/use-cache-bug

but this build passes fully. this is also happening importing posthog provider like so

export function ClientProviders({ children }: { children: React.ReactNode }) {
  useEffect(() => {
    if (isProd) {
      posthog.init(env.NEXT_PUBLIC_POSTHOG_KEY, {
        api_host: env.NEXT_PUBLIC_POSTHOG_HOST,
        capture_pageview: false, // Disable automatic pageview capture, as we capture manually
        capture_pageleave: true,
      });
    }
  }, []);

  return (
    <>
      <Toaster />
      <TRPCReactProvider>
        <PostHogProvider client={posthog}>
          <TooltipProvider>{children}</TooltipProvider>
        </PostHogProvider>
      </TRPCReactProvider>
    </>
  );
}

A recommendation from the team on how we're supposed to handle 3rd party analytics dependencies that leverage things like new Date() would be appreciated.

[followbl]

shipped to production and everything seems to be working great, would love love love to get some insight from someone on the nextjs team if this is the appropriate way to deal with 3rd party analytics dependencies that I don't have the ability to adjust the usage of something like new Date()

I'm highlighting, raising this question as this was a huge thorn in the side of upgrading to dynamicIO which is working exceptionally well everywhere else.

A guide or notation in docs on this I believe would save a bunch of people testing out this feature a lot of heartache.

layout.tsx

export default function Layout({ children }: { children: ReactNode }) {
  return (
    <html
      lang={"en"}
      className="antialiased"
      suppressHydrationWarning
      key="root"
    >
      <body className={cn(lexend.className)}>
        
        <ThemeProvider
          attribute="class"
          defaultTheme="system"
          enableSystem
          disableTransitionOnChange
        >
          <>
            <ClientProviders>
              <HydrateClient>
                <>{children}</>
              </HydrateClient>
            </ClientProviders>
          </>
        </ThemeProvider>
        <SpeedInsights />
      </body>
      <Suspense>
        <CoreAnalytics />
      </Suspense>
    </html>
  );
}

core-analytics.tsx

import { connection } from "next/server";
import { GoogleAnalytics, GoogleTagManager } from "@next/third-parties/google";

import { env } from "~/config/global/env.mjs";
import { Matomo } from "~/lib/trackers/matomo";
import { Pixel } from "~/lib/trackers/pixel";
import { isProd } from "~/lib/utils";
import { TrackSPAPageview } from "./track-spa-pageview";

export async function CoreAnalytics() {
  await connection();

  if (!isProd) {
    return null;
  }

  return (
    <>
      <GoogleAnalytics gaId={env.NEXT_PUBLIC_GA_ID} />
      <GoogleTagManager gtmId={env.NEXT_PUBLIC_GTAG_ID} />
      <TrackSPAPageview />
      <Pixel />
      <Matomo />
    </>
  );
}

posthog-provider

"use client";

import { Suspense, useEffect } from "react";
import dynamic from "next/dynamic";
import posthog from "posthog-js";

import { env } from "~/config/global/env.mjs";
import { isProd } from "~/lib/utils";

const PostHogProviderBase = dynamic(
  () => import("posthog-js/react").then((mod) => mod.PostHogProvider),
  {
    ssr: false,
    loading: () => null,
  },
);

export function PostHogProvider({ children }: { children: React.ReactNode }) {
  useEffect(() => {
    if (isProd) {
      posthog.init(env.NEXT_PUBLIC_POSTHOG_KEY, {
        api_host: env.NEXT_PUBLIC_POSTHOG_HOST,
        capture_pageview: false, // Disable automatic pageview capture, as we capture manually
        capture_pageleave: true,
      });
    }
  }, []);

  return (
    <Suspense>
      <PostHogProviderBase client={posthog}>{children}</PostHogProviderBase>
    </Suspense>
  );
}

client-providers.tsx

import { Toaster } from "@metaintro/ui/sonner";
import { TooltipProvider } from "@metaintro/ui/tooltip";

import { TRPCReactProvider } from "~/trpc/react";
import { PostHogProvider } from "../analytics/posthog-provider";

export function ClientProviders({ children }: { children: React.ReactNode }) {
  return (
    <>
      <Toaster />

      <TRPCReactProvider>
        <PostHogProvider>
          <TooltipProvider>{children}</TooltipProvider>
        </PostHogProvider>
      </TRPCReactProvider>
    </>
  );
}

[followbl]

yea, this is still an issue in production, randomly getting this error and cannot fix for the life of me

[gnoff]

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.

[followbl]

Thanks Josh, I cannot tell you how helpful it is to have a Next team member give a detailed reply on some of these cutting edge features as they are being developed. I hope our willingness to knowingly test these features in production and provide feedback is helpful to the team.

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.

The reply above is very detailed and helpful. I am completely on board with it and believe dynamicIO with ppr is the right move.

The wrapping of a Suspense boundary unfortunately does not fix the error you are referring to. I have tried this multiple different ways to get our analytics libs (which as you mentioned I do not have control over) to load appropriately.

What I would say is incredibly annoying is I don't know why these errors are happening non-deterministically.

I've also tried some of the gimmicks to render the pieces client-side too and am still receiving the error in production.