Skip to main content

Common Errors

Hydration Error

While rendering your application, there was a difference between the React tree that was pre-rendered from the server and the React tree that was rendered during the first render in the browser (hydration).

Hydration is when React converts the pre-rendered HTML from the server into a fully interactive application by attaching event handlers.

Hydration errors can occur from:

  1. Incorrect nesting of HTML tags
    1. <p> nested in another <p> tag
    2. <div> nested in a <p> tag
    3. <ul> or <ol> nested in a <p> tag
    4. Interactive Content cannot be nested (<a> nested in a <a> tag, <button> nested in a <button> tag, etc.)
  2. Using checks like typeof window !== 'undefined' in your rendering logic
  3. Using browser-only APIs like window or localStorage in your rendering logic
  4. Using time-dependent APIs such as the Date() constructor in your rendering logic
  5. Browser extensions modifying the HTML
  6. Incorrectly configured CSS-in-JS libraries
    1. Ensure your code is following our official examples
  7. Incorrectly configured Edge/CDN that attempts to modify the html response, such as Cloudflare Auto Minify

Possible Ways to Fix It

The following strategies can help address this error:

Solution 1: Using useEffect to run on the client only

Ensure that the component renders the same content server-side as it does during the initial client-side render to prevent a hydration mismatch. You can intentionally render different content on the client with the useEffect hook.

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

During React hydration, useEffect is called. This means browser APIs like window are available to use without hydration mismatches.

Solution 2: Disabling SSR on specific components

Next.js allows you to disable prerendering on specific components, which can prevent hydration mismatches.

import dynamic from 'next/dynamic' const NoSSR = dynamic(() => import('../components/no-ssr'), { ssr: false }) export default function Page() {  return (    <div>      <NoSSR />    </div>  )}

Solution 3: Using suppressHydrationWarning

Sometimes content will inevitably differ between the server and client, such as a timestamp. You can silence the hydration mismatch warning by adding suppressHydrationWarning={true} to the element.

<time datetime="2016-10-25" suppressHydrationWarning />

Common iOS issues

iOS attempts to detect phone numbers, email addresses, and other data in text content and convert them into links, leading to hydration mismatches.

This can be disabled with the following meta tag:

<meta  name="format-detection"  content="telephone=no, date=no, email=no, address=no"/>

Browser API's

[Client Components] are prerendered on the server and hydrated on the client.

So the 'use client' directive does not render the page entirely on the client. It will still execute the component code on the server just like in Next.js 12 and under. You need to take that into account when using something like window which is not available on the server.

You can't just check if the window is defined and then immediately update on the client either, since that may cause a mismatch between the server prerender and the client initial render (aka. a hydration error).

To update the page on client load, you need to use a useEffect hook combined with a useState hook. Since useEffect is executed during the initial render, the state updates don't take effect until the next render. Hence, the first render matches the prerender - no hydration errors. More info here: https://nextjs.org/docs/messages/react-hydration-error

Instead of creating this mechanism in every component that needs it, you can make a context that simply sets a boolean using useEffect, telling us we are safe to execute client code.

is-client-ctx.jsx

const IsClientCtx = createContext(false);

export const IsClientCtxProvider = ({ children }) => {
  const [isClient, setIsClient] = useState(false);
  useEffect(() => setIsClient(true), []);
  return (
    <IsClientCtx.Provider value={isClient}>{children}</IsClientCtx.Provider>
  );
};

export function useIsClient() {
  return useContext(IsClientCtx);
}

_app.jsx

function MyApp({ Component, pageProps }) {
  return (
    <IsClientCtxProvider>
      <Component {...pageProps} />
    </IsClientCtxProvider>
  );
}

Usage

  const isClient = useIsClient();
  return (
    <>
      {scrollPosition >= 0 && <FirstModule />}

      {isClient && scrollPosition >= window.innerHeight * 2 && <SecondModule />}
    </>
  );