Hydration Mismatch Error in Next.js When Server Rendered HTML Doesn't Match Client #77039

yinggangtian · 2025-03-12T00:14:00Z

yinggangtian
Mar 12, 2025

Link to the code that reproduces this issue

https://github.com/tianyinggang/blog/tree/nextjs15

To Reproduce

Set up a Next.js app with SSR (Server-Side Rendering).
Add a component that includes dynamic client-specific content.
Use useEffect or similar hooks that cause a mismatch between initial HTML and hydration.
Upon loading the page, observe the hydration mismatch error in the console.

Current vs. Expected behavior

Current:

Expected behavior:

Provide environment information

Operating System:
  Platform: linux
  Arch: x64
  Version: #25~22.04.1-Ubuntu SMP Thu Jan 16 21:37:09 UTC 2025
  Available memory (MB): 7939
  Available CPU cores: 2
Binaries:
  Node: 20.18.1
  npm: 10.8.2
  Yarn: 1.22.22
  pnpm: 9.15.0
Relevant Packages:
  next: 15.3.0-canary.0 // There is a newer canary version (15.3.0-canary.1) available, please upgrade! 
  eslint-config-next: 15.2.2
  react: 19.0.0
  react-dom: 19.0.0
  typescript: 4.9.5
Next.js Config:
  output: N/A
 ⚠ There is a newer canary version (15.3.0-canary.1) available, please upgrade! 
   Please try the latest canary version (`npm install next@canary`) to confirm the issue still exists before creating a new issue.
   Read more - https://nextjs.org/docs/messages/opening-an-issue

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

CSS, Not sure

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

next dev (local)

Additional context

No response

yinggangtian · 2025-03-12T01:15:50Z

yinggangtian
Mar 12, 2025
Author

Error: Hydration failed because the server rendered HTML didn't match the client. As a result this tree will be regenerated on the client. This can happen if a SSR-ed Client Component used:

A server/client branch if (typeof window !== 'undefined').
Variable input such as Date.now() or Math.random() which changes each time it's called.
Date formatting in a user's locale which doesn't match the server.
External changing data without sending a snapshot of it along with the HTML.
Invalid HTML tag nesting.

It can also happen if the client has a browser extension installed which messes with the HTML before React loaded.

https://react.dev/link/hydration-mismatch

  <HotReload assetPrefix="" globalError={[...]}>
    <AppDevOverlay state={{nextId:1, ...}} globalError={[...]}>
      <AppDevOverlayErrorBoundary globalError={[...]} onError={function bound dispatchSetState}>
        <ReplaySsrOnlyErrors>
        <DevRootHTTPAccessFallbackBoundary>
          <HTTPAccessFallbackBoundary notFound={<NotAllowedRootHTTPFallbackError>}>
            <HTTPAccessFallbackErrorBoundary pathname="/" notFound={<NotAllowedRootHTTPFallbackError>} ...>
              <RedirectBoundary>
                <RedirectErrorBoundary router={{...}}>
                  <Head>
                  <link>
                  <script>
                  <script>
                  <script>
                  <Layout>
                    <RootLayoutClient>
                      <html
                        lang="en"
-                         className="light"
-                         style={{color-scheme:"light"}}
                      >
                        <head>
                        ...
                          <div ref={{current:null}} className="about-pane...">
                            <section id="whoami" className="section">
                              <div className="text-center">
+                                 rgb(0, 122, 122)
-                                 rgb(5 206 145)
                                ...
                              ...
                            ...
                  ...
      ...

at throwOnHydrationMismatch (https://reimagined-fiesta-q9p5ggxjvp7f4q7g-3000.app.github.dev/_next/static/chunks/node_modules_next_dist_compiled_2ce9398a._.js:9266:56)
at completeWork (https://reimagined-fiesta-q9p5ggxjvp7f4q7g-3000.app.github.dev/_next/static/chunks/node_modules_next_dist_compiled_2ce9398a._.js:9584:36)
at runWithFiberInDEV (https://reimagined-fiesta-q9p5ggxjvp7f4q7g-3000.app.github.dev/_next/static/chunks/node_modules_next_dist_compiled_2ce9398a._.js:3501:74)
at completeUnitOfWork (https://reimagined-fiesta-q9p5ggxjvp7f4q7g-3000.app.github.dev/_next/static/chunks/node_modules_next_dist_compiled_2ce9398a._.js:10233:23)
at performUnitOfWork (https://reimagined-fiesta-q9p5ggxjvp7f4q7g-3000.app.github.dev/_next/static/chunks/node_modules_next_dist_compiled_2ce9398a._.js:10170:28)
at workLoopConcurrentByScheduler (https://reimagined-fiesta-q9p5ggxjvp7f4q7g-3000.app.github.dev/_next/static/chunks/node_modules_next_dist_compiled_2ce9398a._.js:10164:58)
at renderRootConcurrent (https://reimagined-fiesta-q9p5ggxjvp7f4q7g-3000.app.github.dev/_next/static/chunks/node_modules_next_dist_compiled_2ce9398a._.js:10146:71)
at performWorkOnRoot (https://reimagined-fiesta-q9p5ggxjvp7f4q7g-3000.app.github.dev/_next/static/chunks/node_modules_next_dist_compiled_2ce9398a._.js:9784:176)
at performWorkOnRootViaSchedulerTask (https://reimagined-fiesta-q9p5ggxjvp7f4q7g-3000.app.github.dev/_next/static/chunks/node_modules_next_dist_compiled_2ce9398a._.js:10796:9)
at MessagePort.performWorkUntilDeadline (https://reimagined-fiesta-q9p5ggxjvp7f4q7g-3000.app.github.dev/_next/static/chunks/node_modules_next_dist_compiled_2ce9398a._.js:1952:64)
at div (<anonymous>)
at AboutSection (https://reimagined-fiesta-q9p5ggxjvp7f4q7g-3000.app.github.dev/_next/static/chunks/_d2be61b4._.js:1836:223)
at HomePage (https://reimagined-fiesta-q9p5ggxjvp7f4q7g-3000.app.github.dev/_next/static/chunks/_d2be61b4._.js:3723:235)
at Page (rsc://React/Server/file:///workspaces/blog/.next/server/chunks/ssr/_9e6f5cd4._.js?43:52:264)

2 replies

samcx Mar 12, 2025
Maintainer

@tianyinggang Since hydrations errors are expected behavior, I have moved this over to discussions.

joetherod Jul 16, 2025

Will this be addressed?

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Hydration Mismatch Error in Next.js When Server Rendered HTML Doesn't Match Client #77039

Uh oh!

{{title}}

Uh oh!

Replies: 1 comment 2 replies

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

Hydration Mismatch Error in Next.js When Server Rendered HTML Doesn't Match Client #77039

Uh oh!

yinggangtian Mar 12, 2025

Link to the code that reproduces this issue

To Reproduce

Current vs. Expected behavior

Provide environment information

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

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

Additional context

Replies: 1 comment · 2 replies

Uh oh!

yinggangtian Mar 12, 2025 Author

Uh oh!

samcx Mar 12, 2025 Maintainer

Uh oh!

joetherod Jul 16, 2025

yinggangtian
Mar 12, 2025

Replies: 1 comment 2 replies

yinggangtian
Mar 12, 2025
Author

samcx Mar 12, 2025
Maintainer