Error: There was an error while hydrating. Because the error happened outside of a Suspense boundary, the entire root will switch to client rendering

Shivan M. —
jump to solution

The Problem

When using Next.js 13 and the App directory, you might encounter the following error when using the <head> tag in your root component:

Error: There was an error while hydrating. Because the error happened outside of a Suspense boundary, the entire root will switch to client rendering

This occurs because Next.js controls the injection of metadata into the <head> tag of the HTML of your page during hydration. By using the <head> tag directly, the server-rendered HTML does not match what is on the client at the time of hydration.

The Solution

In the App Router, use the Metadata API to manage <head> elements. The next/head component does not work in the App Router.

Export a metadata object from your page or layout:

export const metadata = {
  title: "Test Title",
};

export default function Home() {
  return (
    <main>
      <div>
        <h1>Hello World</h1>
      </div>
    </main>
  );
}

For dynamic metadata, use the generateMetadata function:

export async function generateMetadata({ params }) {
  const { slug } = await params;
  return { title: `Page - ${slug}` };
}

Pages Router

If you are using the Pages Router, use the Head component from next/head:

import Head from "next/head";

export default function Home() {
  return (
    <main>
      <Head>
        <title>Test Title</title>
      </Head>
      <div>
        <h1>Hello World</h1>
      </div>
    </main>
  );
}

For additional guidance on fixing hydration errors, see this answer.

More Next.js content

Related Answers

Next.js 13 "window is not defined"
Matthew C. —
Fixing handleHardNavigation errors in Next.js
Stephen Cefali —
TypeScript Error: Unexpected token `div`. Expected jsx identifier
Matthew C. —
Error: Importing a component that needs useState. It only works in a Client Component, but none of its parents are marked with use client, so they're Server Components by default.
Shivan M. —

Considered "not bad" by 4 million developers and more than 150,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.

learn more about sentry join our discord
Sentry