Fixing Hydration Errors in server-rendered Components

Scott Cooper

What are Hydration Errors?

Hydration errors are emitted by react-dom when the server-rendered HTML does not match the HTML that is rendered on the client. This could be the text content of an element, the attributes of an element, or the structure of the DOM.

The common causes of hydration errors are well defined by the nextjs docs:

Next.js Hydration Errors

How to fix Hydration Errors?

The first step is to identify the component that is causing the error. This can be challenging if there are many components on the page or if there is no visual change when the page loads. Reproducing the error locally with a react development build can identify the text that was mismatched between the server and client and nextjs displays an error with some of the elements that were mismatched.

Session Replay can be used to help identify the component that is causing the hydration error. See this changelog for how to get started.

Once the component is identified, the next step is to determine why the server and client rendered different HTML.

1. Fix invalid nesting of HTML elements

If you have rendered a div inside a <p> or nested two <p> elements together, react will rerender the entire page and emit a hydration error. This can happen accidentally if you’re using MDX and have an extra line between two paragraphs. Fixing these can be tricky since you’ll need to find the components that are sending invalid HTML and either swap out the elements used or fix the invalid nesting. The diff Sentry is able to provide can help identify the components that are using invalid HTML. See this changelog for how to get started.

2. Using useEffect to display something different on the client

If you are using typeof window !== 'undefined' in your component to change what the component is rendering based on whether it is server-side or client-side, you may need to use useEffect to change the component after it has been hydrated. Its possible the user will momentairly see the server-rendered HTML before it is changed by the client.

import { useState, useEffect } from 'react' export default function App() { const [isClient, setIsClient] = useState(false) useEffect(() => { setIsClient(true) }, []) return <div>{isClient ? 'isClient true' : 'isClient false'}</div> }

3. Using suppressHydrationWarning

suppressHydrationWarning is part of the react-dom package and can be used to suppress hydration errors. Dates often cause hydration errors because the server and client exist in different timezones or the relative time has changed since the server rendered the page.

To silence hydration warnings on an element, add suppressHydrationWarning={true}:

<time datetime="2024-01-01" suppressHydrationWarning>{new Date().toLocaleDateString()}</time>

Filter these errors out

If these errors are caused by 3rd party scripts or browser extensions, you can filter them out by enabling your Sentry project’s Inbound Filters. Learn more about Inbound Filters

Additional Reading

Get Started With Sentry

Get actionable, code-level insights to resolve Next.js performance bottlenecks and errors.

Run the line of code below to:

  1. Create a free Sentry account

  2. Run the CLI install command to automatically add the Sentry SDK to your project:

    npx @sentry/wizard@latest -i nextjs
  3. Start capturing errors and performance issues

Check our documentation for the latest instructions.

Loved by over 4 million developers and more than 90,000 organizations worldwide, Sentry provides code-level observability to many of the world’s best-known companies like Disney, Peloton, Cloudflare, Eventbrite, Slack, Supercell, and Rockstar Games. Each month we process billions of exceptions from the most popular products on the internet.

Share on Twitter
Bookmark this page
Ask a questionJoin the discussion

Related Answers

A better experience for your users. An easier life for your developers.

    TwitterGitHubDribbbleLinkedinDiscord
© 2024 • Sentry is a registered Trademark
of Functional Software, Inc.