Hydration failed because the initial UI does not match what was rendered on the server.

[Zamiell]

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Prerequisites

• I'm using the latest version of Docusaurus.
• I have tried the npm run clear or yarn clear command.
• I have tried rm -rf node_modules yarn.lock package-lock.json and re-installing packages.
• I have tried creating a repro with https://new.docusaurus.io.
• I have read the console error message carefully (if applicable).

Description

I upgraded my version of Docusaurus (and other dependencies), and now I am getting the following run-time error after deploying my website to production:

Docusaurus React Root onRecoverableError: Error: Minified React error #418; visit https://reactjs.org/docs/error-decoder.html?invariant=418 for the full message or use the non-minified dev environment for full errors and additional helpful warnings.
    at ps (main.5876dbc2.js:2:432456)
    at xr (main.5876dbc2.js:2:505502)
    at Tp (main.5876dbc2.js:2:492976)
    at Sp (main.5876dbc2.js:2:492948)
    at sp (main.5876dbc2.js:2:487998)
    at _ (main.5876dbc2.js:2:556368)
    at MessagePort.V (main.5876dbc2.js:2:556900) ObjectcomponentStack: "\n    at li\n    at p\n    at div\n    at div\n    at m (http://localhost:3000/assets/js/1df93b7f.2c283689.js:1:1042)\n    at div\n    at div\n    at section\n    at g\n    at main\n    at l (http://localhost:3000/assets/js/main.5876dbc2.js:2:107880)\n    at div\n    at I (http://localhost:3000/assets/js/main.5876dbc2.js:2:120020)\n    at l (http://localhost:3000/assets/js/main.5876dbc2.js:2:160297)\n    at c (http://localhost:3000/assets/js/main.5876dbc2.js:2:160630)\n    at http://localhost:3000/assets/js/main.5876dbc2.js:2:149184\n    at l (http://localhost:3000/assets/js/main.5876dbc2.js:2:167130)\n    at f (http://localhost:3000/assets/js/main.5876dbc2.js:2:167322)\n    at h (http://localhost:3000/assets/js/main.5876dbc2.js:2:158106)\n    at b (http://localhost:3000/assets/js/main.5876dbc2.js:2:158199)\n    at p (http://localhost:3000/assets/js/main.5876dbc2.js:2:169184)\n    at f (http://localhost:3000/assets/js/main.5876dbc2.js:2:154731)\n    at h (http://localhost:3000/assets/js/main.5876dbc2.js:2:155668)\n    at http://localhost:3000/assets/js/main.5876dbc2.js:2:168242\n    at kt (http://localhost:3000/assets/js/main.5876dbc2.js:2:149305)\n    at Pt (http://localhost:3000/assets/js/main.5876dbc2.js:2:150091)\n    at b\n    at o (http://localhost:3000/assets/js/main.5876dbc2.js:2:112757)\n    at i (http://localhost:3000/assets/js/main.5876dbc2.js:2:533457)\n    at t (http://localhost:3000/assets/js/main.5876dbc2.js:2:543223)\n    at t (http://localhost:3000/assets/js/main.5876dbc2.js:2:544171)\n    at t (http://localhost:3000/assets/js/main.5876dbc2.js:2:543223)\n    at R (http://localhost:3000/assets/js/main.5876dbc2.js:2:2713)\n    at M (http://localhost:3000/assets/js/main.5876dbc2.js:2:3406)\n    at l (http://localhost:3000/assets/js/main.5876dbc2.js:2:529)\n    at o (http://localhost:3000/assets/js/main.5876dbc2.js:2:201)\n    at m (http://localhost:3000/assets/js/main.5876dbc2.js:2:106701)\n    at l (http://localhost:3000/assets/js/main.5876dbc2.js:2:107880)\n    at K (http://localhost:3000/assets/js/main.5876dbc2.js:2:6794)\n    at t (http://localhost:3000/assets/js/main.5876dbc2.js:2:541437)\n    at t (http://localhost:3000/assets/js/main.5876dbc2.js:2:536748)\n    at t (http://localhost:3000/assets/js/main.5876dbc2.js:2:522358)"digest: null[[Prototype]]: Object
i @ main.5876dbc2.js:2

Since the error is new, I suspect it is a regression in Docusaurus, thus I am posting it here.

Importantly, the error does not appear when running the website in dev (i.e. with docusaurus start), only after doing docusaurus build && docusaurus serve.

Steps to reproduce

git clone https://github.com/IsaacScript/isaacscript.git
cd isaacscript
git checkout b414f35680c44134e7dc1da076308750273ac63d
yarn install
cd packages/docs
npm run start

The website will open. Notice that there are no run-time errors in the browser's JavaScript console. Next, cancel the development server and then do:

npm run build && npm run serve

Notice the run-time error appear.

More info

• My Docusaurus config is fairly ordinary: https://github.com/IsaacScript/isaacscript/blob/main/packages/docs/docusaurus.config.ts
• Nothing is swizzled.
• I am using no custom components or pages.
• I am using a custom theme of docusaurus-theme-search-typesense. However, that seems unrelated to the problem, since the run-time errors persist even after commenting it out.

Your environment

• Public source code: https://github.com/IsaacScript/isaacscript
• Public site URL: https://isaacscript.github.io/
• Docusaurus version used: 3.1.1
• Environment name and version (e.g. Chrome 89, Node.js 16.4): Chrome 121
• Operating system and version (e.g. Ubuntu 20.04.2 LTS): Windows 10

Self-service

• I'd be willing to fix this bug myself.

[slorber]

This is likely not a regression: it was a hydration error that was already there, but React did not tell you about it.

React < 18 did not tell you about such problems, and now it does.

https://react.dev/blog/2022/03/08/react-18-upgrade-guide#other-breaking-changes:~:text=Stricter%20hydration%20errors

The init template of Docusaurus does not have such hydration errors, so it is very likely your code that produces such problems. Try to remove your code until it fixes the problem. Running in docusaurus build --dev mode might help identify the problematic code (although in my experience it also produces false positive errors)

[Zamiell]

Thanks. Using the trick of --dev, I isolated the problem to a bulleted list.

To reproduce the problem, you can use the following steps:

npx create-docusaurus@latest my-website classic --typescript
cd my-website
npm run build && npm run serve

Obviously, observe that there are no errors (since it is a fresh template).
Then, open "./src/components/HomepageFeatures/index.tsx" and change the following text:

      <>
        Docusaurus was designed from the ground up to be easily installed and
        used to get your website up and running quickly.
      </>

To this:

      <>
        <ul>
          <li>foo</li>
          <li>bar</li>
        </ul>
      </>

Then, run npm run build && npm run serve, and you will see the same run-time errors that I was describing in the OP.

Any idea what is wrong? I tried a few things, including changing the fragment (i.e. <>) to <div>, but nothing I tried got past this error.

[slorber]

I don't know what the problem is.
Sometimes an external script, or even a browser extension, can lead to such hydration errors

[Zamiell]

I can reproduce the issue on Microsoft Edge, which does not have any browser extensions. Thus, I assume that this is reproducible for everybody by copy-pasting the steps from my previous post (not OP). Do you want me to open a new issue?

[slorber]

If you want to open an issue, please create a minimal repro instead of giving us a link to an existing site. Start from a brand new Docusaurus site, and add the smallest possible changes to make the issue appear.

I can't spend hours investigating your existing site and removing things one by one until we know what causes the problem, so I kindly ask you to do this investigation first before opening this issue. If you can't repro from a newly initialized site, that's likely a bug you introduced, by using code or a third-party plugin that has a bug.

[slorber]

Sorry, didn't see your instructions above.

Indeed I can reproduce the issue, and get the following errors in dev mode:

react-dom.development.js:86 Warning: Expected server HTML to contain a matching <ul> in <p>.
react-dom.development.js:12507 Uncaught Error: Hydration failed because the initial UI does 
react-dom.development.js:86 Warning: An error occurred during hydration. The server HTML was replaced with client content in <div>.
react-dom.development.js:86 Warning: validateDOMNesting(...): <ul> cannot appear as a

This is not a valid repro because it is forbidden to put ul in a paragraph, as stated in the error message.

<p>
        <ul>
          <li>foo</li>
          <li>bar</li>
        </ul>
</p>

You can find many resources related to what cause hydration errors in React online. Those apply to Docusaurus as well.