Issue Station
Sign In
Tools hereToolbox

nextjs - 💡(How to fix) Fix hydration bug [1 comments, 2 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#86183•Fetched 2026-04-08 02:12:07
View on GitHub
Comments
1
Participants
2
Timeline
8
Reactions
0
Author
AlexeyLoktevAlexeyLoktev
Participants
AlexeyLoktevAlexeyLoktevgithub-actions[bot]github-actions[bot]
Timeline (top)
labeled ×4closed ×1commented ×1issue_type_added ×1

Error Message

  1. Refresh the page in the browser. You see "bbb" on the webpage, but an error in the browser console appears: Uncaught Error: Hydration failed because the server rendered text didn't match the client. As a result this tree will be regenerated on the client.
  • without [...notFound] page the error disappears
  • without "Suspense" in the page.tsx the error disappears
  • without "await new Promise" in the page.tsx the error disappears
  • with webpack instead of turbopack the error disappears
  • "bbb" on the page without any error messages in the browser's console
  • "bbb" on the page and an error messages in the browser's console Turbopack, Error Handling, React The "steps to reproduce" reliably lead to the error, but sometimes this (or a related) error appears in other forms as well - for instance, after refreshing the page (the same repo!) the error may say that some source file is not found, but this file isn't expected to exist - I've just changed the code and removed the file and its usage.

Root Cause

  1. Start "npm run dev".
  2. Open "http://localhost:3000/" in the browser.
  3. You see "aaa". Server's console shows "aaa" and a fresh timestamp (first red selection on the screenshot). That's what ClientComponent renders and does.
  4. Not stopping the "npm run dev", change "aaa" to "bbb" in your editor in the source code of ClientComponent.
  5. In the browser you see "bbb" without refreshing the page. Hot reload works well.
  6. Refresh the page in the browser. You see "bbb" on the webpage, but an error in the browser console appears: Uncaught Error: Hydration failed because the server rendered text didn't match the client. As a result this tree will be regenerated on the client. and it shows the difference: there is: bbb there was: aaa and "aaa" and a fresh timestamp in the server's console (second red selection on the screenshot). So, AFAIU, the server executes the old version of the source code.

Code Example

Operating System:
  Platform: win32
  Arch: x64
  Version: Windows 11 Enterprise
  Available memory (MB): 40744
  Available CPU cores: 8
Binaries:
  Node: 22.13.0
  npm: 10.9.2
  Yarn: N/A
  pnpm: N/A
Relevant Packages:
  next: 16.0.1 // There is a newer version (16.0.3) available, upgrade recommended! 
  eslint-config-next: N/A
  react: 19.2.0
  react-dom: 19.2.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/AlexeyLoktev/hydration-bug

To Reproduce

  1. Start "npm run dev".
  2. Open "http://localhost:3000/" in the browser.
  3. You see "aaa". Server's console shows "aaa" and a fresh timestamp (first red selection on the screenshot). That's what ClientComponent renders and does.
  4. Not stopping the "npm run dev", change "aaa" to "bbb" in your editor in the source code of ClientComponent.
  5. In the browser you see "bbb" without refreshing the page. Hot reload works well.
  6. Refresh the page in the browser. You see "bbb" on the webpage, but an error in the browser console appears: Uncaught Error: Hydration failed because the server rendered text didn't match the client. As a result this tree will be regenerated on the client. and it shows the difference: there is: bbb there was: aaa and "aaa" and a fresh timestamp in the server's console (second red selection on the screenshot). So, AFAIU, the server executes the old version of the source code.
<img width="1249" height="979" alt="Image" src="https://github.com/user-attachments/assets/f7361430-5ee7-46e7-8a50-67d96198d88c" /> All the pieces of the example project are important for the bug to appear:
  • without [...notFound] page the error disappears
  • without "Suspense" in the page.tsx the error disappears
  • without "await new Promise" in the page.tsx the error disappears
  • with webpack instead of turbopack the error disappears

Removing .next folder before running "npm run dev" doesn't help. I've tried with Next@15 and Next@16, the bug appears.

Current vs. Expected behavior

After refreshing the page, I expect:

  • "bbb" on the page without any error messages in the browser's console
  • "bbb" in the server's console (with a fresh timestamp)

I really get:

  • "bbb" on the page and an error messages in the browser's console
  • "aaa" in the server's console (with a fresh timestamp)

Provide environment information

Operating System:
  Platform: win32
  Arch: x64
  Version: Windows 11 Enterprise
  Available memory (MB): 40744
  Available CPU cores: 8
Binaries:
  Node: 22.13.0
  npm: 10.9.2
  Yarn: N/A
  pnpm: N/A
Relevant Packages:
  next: 16.0.1 // There is a newer version (16.0.3) available, upgrade recommended! 
  eslint-config-next: N/A
  react: 19.2.0
  react-dom: 19.2.0
  typescript: 5.9.3
Next.js Config:
  output: N/A

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

Turbopack, Error Handling, React

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

next dev (local)

Additional context

The "steps to reproduce" reliably lead to the error, but sometimes this (or a related) error appears in other forms as well - for instance, after refreshing the page (the same repo!) the error may say that some source file is not found, but this file isn't expected to exist - I've just changed the code and removed the file and its usage. It means AFAIU, the source code being executed on the server is one step behind my real source code; refreshing the page makes the server see the up-to-date version of the source code.

extent analysis

TL;DR

The issue can be resolved by upgrading to the latest version of Next.js, as the current version 16.0.1 may have a bug that causes the server to execute an outdated version of the source code.

Guidance

  • The error message "Hydration failed because the server rendered text didn't match the client" suggests that there is a mismatch between the server-rendered and client-rendered content, which could be caused by the server executing an outdated version of the source code.
  • The fact that the error disappears when using webpack instead of turbopack suggests that the issue may be related to turbopack.
  • Upgrading to the latest version of Next.js (16.0.3) may resolve the issue, as the current version 16.0.1 may have a bug that causes this behavior.
  • If upgrading is not possible, trying to disable turbopack or using a different build tool may help mitigate the issue.

Example

No code snippet is provided as the issue is more related to the build and deployment process rather than a specific code snippet.

Notes

The issue seems to be specific to the combination of Next.js, turbopack, and the next dev command. The fact that the error disappears when using webpack or removing certain components suggests that the issue is related to the build and deployment process.

Recommendation

Upgrade to the latest version of Next.js (16.0.3) to resolve the issue, as the current version 16.0.1 may have a bug that causes the server to execute an outdated version of the source code.

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…
#index setup#retrieval issue#search optimization#API routing#API middleware

Still need to ship something?

×6

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

Back to top recommendations

TRENDING