Hydration errors in Cypress when using React 18, Next, and server components #27204

liambutler · 2023-07-05T14:24:35Z

Current behavior

I’ve got a Next app running React 18. In the next.config.js, it has been configured with appDir to support Server Components. When running Cypress and accessing the page, I’m getting the following React errors:

(uncaught exception)Error: Hydration failed because the initial UI does not match what was rendered on the server. Warning: Expected server HTML to contain a matching <script> in <head>. See more info here: https://nextjs.org/docs/messages/react-hydration
 (uncaught exception)Error: There was an error while hydrating. Because the error happened outside of a Suspense boundary, the entire root will switch to client rendering.

However, I do not see these hydration issues when accessing the page via browser, so it’s surprising to see them when running Cypress.

Steps to replicate:

Clone repo and run npm install
Run npm run e2e
Visit http://localhost:3000 in your browser and check for console errors
Run the spec app.cy.ts

Here's what I see in Cypress:

It's not there when visiting the app via browser:

The error will no longer appear if you remove the <script> tag on line 10 of layout.tsx (link to repro code)

Seeing as this script tag isn't causing errors when accessing via the browser, I can only conclude that it's being caused by how Cypress is loading this page when React Server Components are present

The error occurs both when the app is running in dev mode, and when you visit the application in production mode after running build and start. In production mode, the errors are minified:

(uncaught exception)Error: Minified React error #418; visit https://reactjs.org/docs/error-decoder.html?invariant=418
(uncaught exception)Error: Minified React error #423; visit https://reactjs.org/docs/error-decoder.html?invariant=423

I’ve seen this issue raised in a few places. The suggestion I usually see is to prevent the tests from failing due to this uncaught exception (eg here), or to catch the issue in the application (Cypress docs)

As far as I have managed to understand, there should never be a hydration mismatch in a server rendered component since there is no client rendering to match it to. And when accessing the app via the browser, there are no mismatch errors. So I can only conclude that the issue stems from how Cypress is loading the page.

Desired behavior

Cypress should not be causing uncaught exceptions. Any exceptions that occur should also be triggered under the same conditions via browser

Test code to reproduce

https://github.com/liambutler/cypress-react-next-hydration-issue

Cypress Version

12.16.0

Node version

18.16.0

Operating System

MacOS 13.4.1

Debug Logs

No response

Other

Edit 8th November 2023- since updating Next.js from 13.4.2 to 13.5.6, we are also seeing this uncaught exception:

Minified React error 329; visit https://reactjs.org/docs/error-decoder.html?invariant=329 ("Unknown root exit status.")

This also only appears when Cypress is being injected into the browser

The text was updated successfully, but these errors were encountered:

marktnoonan · 2023-07-05T17:40:59Z

Hi Liam 👋 - based on the error and the fact that it happens based on simply including a script tag in the server rendered <head>, I have a bit of a guess about what's going on.

The key factor may be that Cypress adds a script tag to the <head> of pages that are visited through Cypress. The Cypress <script> sets up window.Cypress and some other critical stuff, and is injected at the top of the <head> before the page is served. It's important that it be there on initial load since other code further down the page may rely on this global being present.

The <script> tag from your RSC is at the bottom of the head. I suspect that what is happening during hydration is that, since the validator knows to expect a <script> tag, it is parsing the head and finding the one injected by Cypress, and attempting to diff that against the <script></script> from your JSX.

I don't have a workaround at the moment besides ignoring hydration errors, which as you've said it not ideal, they are still there.

I'm assuming the use case here is going to be pretty common - you want to write some inline JS in your <head> so that it is active immediately on page load in your Next app?

jcmonteiro · 2023-07-06T07:32:42Z

Hi Mark! Thanks for the reply. Liam and I work together, and I might be able to provide some more context. Your explanation makes total sense. We also observe the problem when adding an empty <style> tag to <head>. From what you've said, it seems like the root cause is the same, i.e., Cypress's looking for its injected <script> tag and finding something of ours instead.

We indeed want an inline JS to execute as soon as the page is loaded. For context, that inline JS will test the browser against a series of modern JS commands, immediately redirecting (location.replace) the session to a simple "please upgrade your browser" page if such commands are not supported. That provides the best experience since we don't need to wait for all the JS to load, potentially breaking the session if the user is running on an old browser.

The <style> tag I mentioned is used to globally set the style of some elements. It is needed because the setup we have to produce our CSS design tokens strips away some properties that we then enforce back via <style dangerouslySetInnerHTML={{ __html: minifiedCss }} />

marktnoonan · 2023-07-07T13:52:00Z

Thanks @jcmonteiro

Cypress's looking for its injected <script> tag and finding something of ours instead.

It's actually the other way around, Cypress doesn't care about any of this, but my guess is, where React is expecting the innerHtml of <head> to be the same on the client and server, it's not able to ignore the <script> tag added by Cypress. It's not clear to me why Next doesn't throw these errors always, why it only happens when either <style> or <script> is present as you've noticed. But maybe there are some rules/shortcuts for what it checks based on the contents of the JSX.

Cypress adds the script before the HTML is sent over the wire to the browser, in between the application server and the client, so there is no way for the Cypress JS to not be in the HTML sent to the client and evaluated during hydration.

It's similar to the problems that would happen if you are trying to do something like personalize a page by rewriting the HTML on the edge, after it has been rendered on a server. There's a long blog post from Netlify about the hoops that need to be jumped through to make hydration happy in that situation. Probably any tool that modifies the page contents after server-rendering through some middleware is going to have problems like this to solve with RSC.

I can think of a few workarounds, but I'm not too familiar with React and Next so they might not be ideal. Maybe this gives you enough info to work around it on your own, or to feel comfortable ignoring these errors for the time being. I'll flag this for the team as well so we can see if Cypress can avoid triggering this in the first place.

cacieprins · 2023-07-07T14:22:04Z

Hi Liam and Joāo, Thank you so much for the reproduction case - it was very helpful in troubleshooting. I think I have a workaround for you. Can you try to wrap the style and script elements in a React.Suspense component?

I tested this in the reproduction case along with some small edits to more closely fit your use case, and it seems to no longer throw the hydration error when running in Cypress.

<Suspense>
  <script dangerouslySetInnerHTML={{ __html : `if(window.location.pathname === '/') { window.location.replace('http://localhost:3000/redirected') }` }}></script>
  <style dangerouslySetInnerHTML={{ __html: `body { color: #676 }`}} ></style>
</Suspense>

Please let us know if that helps!

jcmonteiro · 2023-07-10T09:22:01Z

Hi Cacie, you are welcome and thank you for the reply.

Although the <Suspense> can help, I don't see it as a viable option for us. The reason is that our strategy for putting the "browser validation" <script> in the top-level <head> is that it can run before any JS is loaded (including the one that resolves the <Suspense>). As for the <style> element, I fear that wrapping it in a <Suspense> might lead to unforeseen issues in a larger application.

cacieprins · 2023-07-10T13:48:25Z

I was worried about that too, so I did some digging. It turns out that Suspense contents do get rendered by SSR, so that code will execute before your main application code. You can see this come over the wire in network dev tools as a pair of comments.

The only other path forward I can see for this issue is configuring your build system inject the desired <script> and <style> tags outside of the react tree, similar to the other build artifacts. This would prevent hydration from trying to associate a React script component with the scripts that cypress injects. I'm not familiar enough with next.js to aid with this, however.

jcmonteiro · 2023-07-10T14:00:51Z

We will likely continue to catch the warnings and discard them in our Cypress tests, but it's not ideal since we might end up discarding true hydration errors. Could you keep this issue open so the community (ourselves included) can track its progress?

karlhorky · 2023-07-21T16:53:11Z

I'm experiencing the 418 and 423 hydration errors with Cypress tests (currently suspecting usage of the cy.window() API via gatsby-cypress) as well also with Gatsby and a new canary version of React (18.3.0-canary-7118f5dd7-20230705)

Next.js uses canary React internally, which may be one of the reasons that it is visible there.

But if this indicates a general hydration problem with React 18.3.0, then Cypress may have problems with many more applications when a non-canary version of React 18.3.0 is released.

References:

Other software like browser extensions are also having issues over here Bug: Hydration mismatch error due to plugins generating script tag on top facebook/react#24430

karlhorky · 2023-07-21T17:19:05Z

Workaround

In case you're wondering how exactly to disable the uncaught exception errors in Cypress as Liam and João mentioned:

@liambutler in PR description: prevent the tests from failing due to this uncaught exception (eg here),

@jcmonteiro in comment 1629028523: We will likely continue to catch the warnings and discard them in our Cypress tests

...here's an example which was working for us (add block 1 before the test code that causes the failure, add block 2 after the test code that causes the failure):

// 1. Disable Cypress uncaught exception failures from React hydration errors
Cypress.on('uncaught:exception', (err) => {
  if (
    err.message.includes('Minified React error #418') ||
    err.message.includes('Error: Minified React error #423')
  ) {
    return false;
  }
  // Enable uncaught exception failures for other errors
});

// 2. Re-enable Cypress uncaught exception failures from React hydration errors
Cypress.on('uncaught:exception', () => {});

minimit · 2023-08-07T08:16:52Z

Happends also if you put in the <head> tag a stylesheet link <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;700;900&display=swap" rel="stylesheet"/>

liambutler · 2023-08-21T15:30:33Z

@cacieprins would it be possible to remove the 'existing workaround' tag from this ticket? I believe that the exceptions are causing issues for my tests despite the Cypress.on('uncaught:exception' catch detailed above

jcmonteiro · 2023-08-22T14:18:37Z

I will also add that the workaround interferes with the tests in a way that errors might go unnoticed. Thus, I also advocate for removing the existing workaround tag since it undermines the purpose of using Cypress.

marktnoonan · 2023-08-24T20:02:28Z

I've been interpreting the "existing workaround" tag as referring to the use of <Suspense> mentioned here and other options around building mentioned here.

I don't see squashing the errors as a workaround - that's just ignoring errors - but I do see structuring your application in a way that it won't yell about injecting JS needed for testing as a workaround, which while inconvenient might not be too painful.

I'm interested in the reasons people might not find those options acceptable/feasible - and if you have tried any of them before choosing to ignore the error. Eg if somebody has tried the <Suspense> solution, did you find it didn't solve the problem, or it solved the problem but introduced unwanted side effects?

jcmonteiro · 2023-08-27T10:42:19Z

In our use case, the issue with the <Suspense> is the one I mentioned previously.

The reason is that our strategy for putting the "browser validation" <script> in the top-level is that it can run before any JS is loaded (including the one that resolves the )

This is just our use case. In any case, adding the <Suspense> changes the execution flow substantially, so I would recommend against it, given the wide variety of use cases that are difficult to foresee.

marktnoonan · 2023-08-29T02:04:47Z

Thanks @jcmonteiro - for clarity, what I am interested in is: have you verified that it does or would in fact cause a problem, given our understanding the <Suspense> is resolved during SSR and comes over the wire with the initial payload HTML, causing no need to wait for JS to load on the client to deliver the contents?

I'm not saying that you should accept/implement the workarounds, it's valid to be cautious. But at the moment I can't tell for sure which of these we are dealing with:

Option 1: <Suspense> works, but is a workaround that you find unacceptable due to an abundance of caution around possible unexpected side effects later (I think this is where we are)

Option 2: <Suspense> doesn't solve the problem because the information in this comment is incorrect and SSR is not resolving the contents on the server in your case

@cacieprins also mentioned "configuring your build system inject the desired <script> and <style> tags outside of the react tree, similar to the other build artifacts" so I'd have a similar question about that option: is this something that you tried and it didn't work, or didn't try (for whatever reason)?

liambutler · 2023-09-06T09:27:40Z

Hi @marktnoonan

You're right in that we're at option 1. I've wrapped the scripts in <Suspense> and no longer see the exceptions. I've also tested the application on older browsers to ensure that the compatibility check script still works (see this earlier comment from @jcmonteiro ), and all still works as expected.

However, I'm getting a lot of pushback from the team around making a change like this to our layout.tsx, and I can see their point. Should we be making fundamental changes to our application in order to have a workaround for an issue caused by our choice of e2e tool? It's not an easy sell. (I haven't tried @cacieprins' suggestion, but the pushback would be much the same)

karlhorky · 2023-09-06T11:10:38Z

Should we be making fundamental changes to our application in order to have a workaround for an issue caused by our choice of e2e tool? It's not an easy sell.

Yeah, I would guess this is enough for many teams to switch from Cypress to Playwright. I know that I would, if I was in that situation.

brian-mann · 2023-09-08T14:59:40Z

Hey @liambutler ... @marktnoonan brought this to my attention and I am recommending and testing out an approach where we automatically cleanup our injections before any of your react code runs, which may actually fix this issue and not require any changes on your side. We're going to put together a POC and may want ya'll to try out a development version of this fix to confirm it works.

This is a very simple example:

<html>
  <head>
    <script type="text/javascript">window.foo = {}; document.currentScript.remove()</script>

    <script type="text/javascript">console.log(window.foo)</script>
  </head>
</html>

liambutler · 2023-09-11T10:33:27Z

Hi @brian-mann, thanks for looking into this!

Happy to help test any fix builds you want to try out. Let me know

0420syj · 2023-09-12T00:07:59Z

Happends also if you put in the <head> tag a stylesheet link <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;700;900&display=swap" rel="stylesheet"/>

Hi @minimit
In my case, I had the same problem when using the following.

<head>
  <link
    rel="stylesheet"
    as="style"
    crossOrigin="anonymous"
    href="https://cdnjs.cloudflare.com/ajax/libs/pretendard/1.3.8/static/pretendard.css"
  />
</head>

Changing the rel attribute to preload solved the problem.

<head>
  <link
    rel="preload"
    as="style"
    crossOrigin="anonymous"
    href="https://cdnjs.cloudflare.com/ajax/libs/pretendard/1.3.8/static/pretendard.css"
  />
</head>

Hope this works for you !

marktnoonan · 2023-09-12T14:59:27Z

Hi folks, I've confirmed that the modification suggested by @brian-mann to have Cypress clean up the script element as the last step in its execution does not solve this issue, though I think it will be part of the final solution.

Reading through the thread in the React repo that @karlhorky linked to (facebook/react#24430) was interesting, in that people reported hydration errors with the likes of Loom and other browser extensions that modify the DOM, not just when testing with Cypress.

This makes sense based on the the nature of the problem. And it seems like the React team is aware of these consequences of stricter hydration rules and has worked to mitigate them in previous releases. I'm curious what will happen when 18.3.0 is stable. One thing we can test is a recent canary build that seems to fix a similar hydration problem for one person here: remix-run/remix#4822 (comment)

To summarize: We will look into the long term way for Cypress to handle this kind of error, or to at least confirm that it is handled upstream in React.

The "existing workaround" label doesn't mean that we won't work on it, just that there are ways to become unblocked in the meantime and allow your tests to run.

dkasper-was-taken · 2023-09-25T17:53:20Z

Tested example repo with latest 18.3.0-canary-9ba1bbd65-20230922, hydration error still present.

bahmutov · 2023-12-04T20:34:36Z

Hitting this problem sometimes. React should respect an element's attribute something like react-ignore-when-hydrating=true in this case.

vahidvdn · 2024-01-16T17:44:45Z

Workaround

Cypress.on("uncaught:exception", (err) => {
  // Cypress and React Hydrating the document don't get along
  // for some unknown reason. Hopefully, we figure out why eventually
  // so we can remove this.
  if (
    /hydrat/i.test(err.message) ||
    /Minified React error #418/.test(err.message) ||
    /Minified React error #423/.test(err.message)
  ) {
    return false;
  }
});

One important note regarding this, it should be in the e2e.ts in the cypress/support directory. Otherwise it won't work

n-l-i · 2024-01-24T21:06:06Z

Hi folks, I've confirmed that the modification suggested by @brian-mann to have Cypress clean up the script element as the last step in its execution does not solve this issue, though I think it will be part of the final solution.

Reading through the thread in the React repo that @karlhorky linked to (facebook/react#24430) was interesting, in that people reported hydration errors with the likes of Loom and other browser extensions that modify the DOM, not just when testing with Cypress.
. . .

In that thread they also discuss the workaround of modifying the code so that the <head> is not hydrated, only the <body>. This works rather well for me. See the example in this comment: facebook/react#24430 (comment)

BKG01 · 2024-02-05T14:09:28Z

Workaround

Cypress.on("uncaught:exception", (err) => {
  // Cypress and React Hydrating the document don't get along
  // for some unknown reason. Hopefully, we figure out why eventually
  // so we can remove this.
  if (
    /hydrat/i.test(err.message) ||
    /Minified React error #418/.test(err.message) ||
    /Minified React error #423/.test(err.message)
  ) {
    return false;
  }
});

One important note regarding this, it should be in the e2e.ts in the cypress/support directory. Otherwise it won't work

This was the simplest solution for me (removing any stylesheet etc... in the head didn't fix the error). (Using remix with tailwind).
One thing to note is that all my tests were failing due to this error, it wasn't just an error that could be ignored (which may not be obvious given the above). I'll use the workaround until the react team have a more permanent solution. Thx

RandallRock123 · 2024-04-03T02:02:35Z

Hi Liam 👋 - based on the error and the fact that it happens based on simply including a script tag in the server rendered <head>, I have a bit of a guess about what's going on.

The key factor may be that Cypress adds a script tag to the <head> of pages that are visited through Cypress. The Cypress <script> sets up window.Cypress and some other critical stuff, and is injected at the top of the <head> before the page is served. It's important that it be there on initial load since other code further down the page may rely on this global being present.

The <script> tag from your RSC is at the bottom of the head. I suspect that what is happening during hydration is that, since the validator knows to expect a <script> tag, it is parsing the head and finding the one injected by Cypress, and attempting to diff that against the <script></script> from your JSX.

I don't have a workaround at the moment besides ignoring hydration errors, which as you've said it not ideal, they are still there.

I'm assuming the use case here is going to be pretty common - you want to write some inline JS in your <head> so that it is active immediately on page load in your Next app?

I have to remember this one, when somthing is only happenning on certain modern browser, I just diabled the extensions, then it worked!

nelsondev19 · 2024-04-28T23:18:14Z

Hello everyone, I had the same problem and I solved it with the following example:

Next JS version: 14.2.3

/context/StyledComponentsRegistry/index.tsx

"use client";

import { useServerInsertedHTML } from "next/navigation";

export function StyledComponentsRegistry({
  children,
  dynamicStyle,
}: {
  children: React.ReactNode;
  dynamicStyle: string;
}) {
  useServerInsertedHTML(() => {
    return <style>{dynamicStyle}</style>;
  });

  if (typeof window !== "undefined") return <>{children}</>;

  return <>{children}</>;
}

layout.tsx

import { StyledComponentsRegistry } from "@/context/StyledComponentsRegistry";


export default function RootLayout({ children }: Props) {
  const dynamicStyle = `:root {--bg-brand-sel: #fff;`;

  return (
    <html >
      <body>
        <StyledComponentsRegistry dynamicStyle={dynamicStyle}>
            {children}
        </StyledComponentsRegistry>
      </body>
    </html>
  );
}

yukulelix · 2024-05-07T02:18:58Z

In my case, using experimentalStudio: true in my e2e config was the issue.

defineConfig({
  e2e: {
    baseUrl: "http://localhost:3000",
    experimentalStudio: true,  // <--- Here
  }
 })

Removing it solved my hydration issues.

douglasgf · 2024-05-08T11:55:12Z

Even applying the solutions mentioned here didn't solve it.
When running Cypress, the website doesn't renerise everything and the Login option doesn't appear.

nagash77 assigned cacieprins Jul 5, 2023

cacieprins added the existing workaround label Jul 7, 2023

nagash77 added E2E Issue related to end-to-end testing Triaged Issue has been routed to backlog. This is not a commitment to have it prioritized by the team. labels Jul 11, 2023

warrensplayer assigned jordanpowell88 and unassigned cacieprins Nov 8, 2023

jordanpowell88 removed their assignment Nov 27, 2023

johnGachihi mentioned this issue Dec 30, 2023

Cypress tests and hydration exception johnGachihi/johngachihi.me#60

Open

bklaing2 mentioned this issue Feb 6, 2024

Migrate index page to app router datacite/akita#341

Merged

8 tasks

This was referenced Apr 10, 2024

Workaround for React Hydration Errors with Cypress Linkta-org/landing-page#29

Merged

Workaround for Next.js Errors with Cypress Linkta-org/landing-page#31

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Hydration errors in Cypress when using React 18, Next, and server components #27204

Hydration errors in Cypress when using React 18, Next, and server components #27204

liambutler commented Jul 5, 2023 •

edited

marktnoonan commented Jul 5, 2023

jcmonteiro commented Jul 6, 2023

marktnoonan commented Jul 7, 2023

cacieprins commented Jul 7, 2023

jcmonteiro commented Jul 10, 2023 •

edited

cacieprins commented Jul 10, 2023

jcmonteiro commented Jul 10, 2023

karlhorky commented Jul 21, 2023 •

edited

karlhorky commented Jul 21, 2023 •

edited

minimit commented Aug 7, 2023

liambutler commented Aug 21, 2023

jcmonteiro commented Aug 22, 2023

marktnoonan commented Aug 24, 2023

jcmonteiro commented Aug 27, 2023 •

edited

marktnoonan commented Aug 29, 2023

liambutler commented Sep 6, 2023 •

edited

karlhorky commented Sep 6, 2023

brian-mann commented Sep 8, 2023 •

edited

liambutler commented Sep 11, 2023

0420syj commented Sep 12, 2023

marktnoonan commented Sep 12, 2023

dkasper-was-taken commented Sep 25, 2023

bahmutov commented Dec 4, 2023

vahidvdn commented Jan 16, 2024

Workaround

n-l-i commented Jan 24, 2024

BKG01 commented Feb 5, 2024

Workaround

RandallRock123 commented Apr 3, 2024

nelsondev19 commented Apr 28, 2024

yukulelix commented May 7, 2024

douglasgf commented May 8, 2024

Hydration errors in Cypress when using React 18, Next, and server components #27204

Hydration errors in Cypress when using React 18, Next, and server components #27204

Comments

liambutler commented Jul 5, 2023 • edited

Current behavior

Desired behavior

Test code to reproduce

Cypress Version

Node version

Operating System

Debug Logs

Other

marktnoonan commented Jul 5, 2023

jcmonteiro commented Jul 6, 2023

marktnoonan commented Jul 7, 2023

cacieprins commented Jul 7, 2023

jcmonteiro commented Jul 10, 2023 • edited

cacieprins commented Jul 10, 2023

jcmonteiro commented Jul 10, 2023

karlhorky commented Jul 21, 2023 • edited

karlhorky commented Jul 21, 2023 • edited

Workaround

minimit commented Aug 7, 2023

liambutler commented Aug 21, 2023

jcmonteiro commented Aug 22, 2023

marktnoonan commented Aug 24, 2023

jcmonteiro commented Aug 27, 2023 • edited

marktnoonan commented Aug 29, 2023

liambutler commented Sep 6, 2023 • edited

karlhorky commented Sep 6, 2023

brian-mann commented Sep 8, 2023 • edited

liambutler commented Sep 11, 2023

0420syj commented Sep 12, 2023

marktnoonan commented Sep 12, 2023

dkasper-was-taken commented Sep 25, 2023

bahmutov commented Dec 4, 2023

vahidvdn commented Jan 16, 2024

Workaround

n-l-i commented Jan 24, 2024

BKG01 commented Feb 5, 2024

Workaround

RandallRock123 commented Apr 3, 2024

nelsondev19 commented Apr 28, 2024

yukulelix commented May 7, 2024

douglasgf commented May 8, 2024

liambutler commented Jul 5, 2023 •

edited

jcmonteiro commented Jul 10, 2023 •

edited

karlhorky commented Jul 21, 2023 •

edited

karlhorky commented Jul 21, 2023 •

edited

jcmonteiro commented Aug 27, 2023 •

edited

liambutler commented Sep 6, 2023 •

edited

brian-mann commented Sep 8, 2023 •

edited