Skip to content

useSearchParams in Next.js: the CSR bailout that empties HTML

How the useSearchParams Suspense CSR bailout works in Next.js, why a boundary around the whole page leaves crawlers only a fallback, and three ways to fix it.

By Crawlito · 8 min read

In short

  • On a prerendered Next.js route, useSearchParams makes the Client Component tree up to the closest Suspense boundary render only in the browser, so the static HTML holds that boundary's fallback instead.
  • Without any Suspense boundary, next build fails with the Missing Suspense boundary with useSearchParams error; in development the hook does not suspend, so the problem does not show up there.
  • A Suspense boundary or a loading.js file around the whole page passes the build but leaves crawlers that do not run JavaScript with only the fallback text.
  • The fixes are to wrap the smallest component that reads the query string, to read the searchParams page prop on the server, or to render the route at request time with connection().
  • In our Next.js 16.4.5 test build, a client-rendered boundary showed up as the HTML comment <!--$!--> followed by a template tag, with the real text only inside the RSC payload script.
On this page

When a Next.js route is prerendered, calling useSearchParams in a Client Component makes everything up to the closest <Suspense> boundary render in the browser only. The static HTML gets that boundary's fallback in its place. If the boundary wraps one small search box, nothing is lost. If it wraps the whole page, or the nearest boundary is a route's loading.js, the HTML that crawlers receive contains a loading message and no content, even though the build passed and the page looks fine in a browser.

This post covers what the bailout does to the HTML, how to spot it in a build, and the three documented ways to fix it. The wider Next.js picture (streaming, metadata, useEffect fetching) is in Next.js SEO for AI crawlers, and the general problem of pages that only exist after JavaScript runs is in the empty HTML problem.

What the CSR bailout does

The useSearchParams reference states the rule: if a route is prerendered, calling the hook "will cause the Client Component tree up to the closest Suspense boundary to be client-side rendered." The query string is not known at build time, so Next.js cannot render that part ahead of time. It renders the boundary's fallback into the HTML instead and lets the browser fill in the real component during hydration.

The mechanism comes from React. The Suspense reference explains that when a component throws on the server, React does not abort the render. It finds the closest <Suspense> above it, puts that boundary's fallback into the server HTML, and tries the component again on the client. In the Next.js 16.4.5 source, with Cache Components off, the hook throws a BailoutToCSRError whose message starts "Bail out to client-side rendering", which is how it uses that path. With Cache Components on, it suspends on a promise instead. Either way this is an implementation detail, not documented behaviour.

So the size of the hole in your HTML is decided by one thing: where the nearest boundary sits.

Where the nearest Suspense boundary isWhat next build doesWhat the static HTML contains
None anywhere above the hookFails with the Missing Suspense boundary errorNothing, the build stops
Around the small component that reads the queryPassesThe whole page, with the fallback only where that component goes
Around the whole page bodyPassesThe page-level fallback only
A loading.js file in the route segmentPassesThe loading.js UI only

The last row catches people out. The page.js reference says page.js is wrapped by loading.js, which is a Suspense boundary. If the page has no boundary of its own closer to the hook, loading.js becomes the closest one, and the whole page is client-rendered without any error.

Why the build error appears and why dev hides it

The useSearchParams page notes that in development, routes are rendered on demand, so the hook does not suspend and things "may appear to work without Suspense". During a production build, a static page that calls useSearchParams from a Client Component must be wrapped in a Suspense boundary, or the build fails. The build output looks like this (stack trace trimmed):

⨯ useSearchParams() should be wrapped in a suspense boundary at page "/products". Read more: https://nextjs.org/docs/messages/missing-suspense-with-csr-bailout
Error occurred prerendering page "/products". Read more: https://nextjs.org/docs/messages/prerender-error

The error page explains why it exists: reading search parameters without a boundary "will opt the entire page into client-side rendering", which could leave the page blank until the JavaScript loads. In Next.js 14 you could turn the check off with experimental.missingSuspenseWithCSRBailout: false. The docs say that option was only available in 14.x and that later versions should fix the code instead.

The common quick fix is to wrap the whole page in <Suspense> so the error goes away. That passes the build and produces exactly the outcome the error was warning about, now without a warning. If you use Cache Components, the error you see is a different one, from the instant-navigation validation added in Next.js 16.3, and its blocking-prerender-client-hook page says it directly: a boundary around the whole page body "can pass validation with an empty shell". The same page advises placing the boundary as close to the hook call as possible.

What the HTML looks like in each case

We built a small test app with Next.js 16.4.5 in its default configuration (Cache Components off). Two static routes render a heading, a paragraph and a Client Component that shows the sort query parameter. The only difference is where the boundary goes.

Boundary around the whole page:

tsx
// app/whole/page.tsx
import { Suspense } from 'react'
import { SortLabel } from '../sort-label' // 'use client', calls useSearchParams

export default function Page() {
  return (
    <Suspense fallback={<p>Loading page</p>}>
      <main>
        <h1>Blue widgets</h1>
        <p>Article body text here.</p>
        <SortLabel />
      </main>
    </Suspense>
  )
}

With script tags removed, the body of the prerendered file is:

html
<body><div hidden=""><!--$--><!--/$--></div><!--$!--><template data-dgst=""></template><p>Loading page</p><!--/$--><!--$--><!--/$--></body>

The heading and paragraph are gone. "Blue widgets" still appears once in the file, but only inside the inline scripts that carry the React Server Components payload, which the browser uses to build the page. A crawler that extracts text from HTML and does not run scripts gets "Loading page". What the self.__next_f.push scripts contain explains that payload.

Boundary around the one component that reads the query:

html
<body><div hidden=""><!--$--><!--/$--></div><main><h1>Blue widgets</h1><p>Article body text here.</p><!--$!--><template data-dgst=""></template><p>Sort: default</p><!--/$--></main><!--$--><!--/$--></body>

Same component, same hook, and now everything except the sort label is real HTML. The route with only a loading.js file and no boundary in the page gave the same result as the first case: the body held the loading UI and nothing else.

Note the difference from streaming. With a request-time Suspense boundary, the resolved content is sent later in the same response inside a hidden div, as described in the Next.js guide. With the CSR bailout, the content is never rendered to HTML on the server at all.

How to find a bailout in your build

You do not need a crawler to check this. The prerendered HTML is on disk after next build.

  1. Look for the marker. In the files we tested, React marks a client-rendered boundary with the comment <!--$!--> followed by a <template> tag. List the prerendered pages that contain it:
bash
grep -rl '<!--\$!-->' .next/server/app --include='*.html'
  1. Check what sits next to it. For each file found, strip the scripts and look at the body. If the text after the marker is a short fallback and your main content is missing, the boundary is too high:
bash
perl -0pe 's/<script\b.*?<\/script>//gs' .next/server/app/products.html | grep -o '<body.*</body>'
  1. Check the live page. Fetch the production URL without a browser and search for a sentence from the main content, as in how to see your page as an AI crawler. A count of zero on a page that looks complete in the browser means the text is only added on the client.

  2. Find the component. The error page suggests next build --debug-prerender for unminified stack traces when you need to locate the hook call.

The <!--$!--> marker is React's internal output, not a documented API, so treat it as a quick search aid and confirm with step 3.

Three ways to fix it

1. Wrap the smallest component that reads the query

This is the fix the error page lists first for keeping a route static: move the useSearchParams call into a small child Client Component and wrap only that in <Suspense>. The page stays a Server Component and everything around the boundary is prerendered.

tsx
// app/products/page.tsx (Server Component)
import { Suspense } from 'react'
import { SortControl } from './sort-control' // 'use client', calls useSearchParams

export default async function Page() {
  const products = await getProducts()
  return (
    <main>
      <h1>Blue widgets</h1>
      <Suspense fallback={<span>Sort: featured</span>}>
        <SortControl />
      </Suspense>
      <ProductList products={products} />
    </main>
  )
}

The trade-off is that the query does not change the server HTML. If ?sort=price reorders the list, the HTML still shows the default order, and the browser reorders it after hydration. That is fine for controls and labels. Give the fallback a sensible default and a similar size: the blocking-prerender-client-hook page advises a fallback shape that matches the final layout so the swap does not cause a layout shift.

2. Read the searchParams page prop on the server

If the query decides what content the page shows, read it in the page itself. The page.js reference documents searchParams as a promise (since Next.js 15) and says using it opts the page into dynamic rendering at request time.

tsx
// app/products/page.tsx
export default async function Page({
  searchParams,
}: {
  searchParams: Promise<{ [key: string]: string | string[] | undefined }>
}) {
  const { sort = 'featured' } = await searchParams
  const products = await getProducts({ sort })
  return (
    <main>
      <h1>Blue widgets</h1>
      <ProductList products={products} />
    </main>
  )
}

The server now renders the list for the real query on every request, so the HTML matches what the visitor sees. The route shows as ƒ (Dynamic) in the build output instead of ○ (Static), which means a server render per request. Layouts do not get this prop, because a shared layout is not re-rendered on navigation; the useSearchParams reference covers that.

3. Render the route at request time with connection()

If the whole route should be dynamic anyway, call await connection() from next/server at the top of a Server Component page or layout. The docs say this waits for an incoming request and excludes everything below it from prerendering, and that on a dynamically rendered route useSearchParams is available during the initial server render. Older code used export const dynamic = 'force-dynamic' for the same purpose; the error page notes that setting it in a 'use client' page has no effect.

FixRoute stays static?Query reflected in server HTML?Best for
Small boundary around the hookYesNo, fallback in its placeSearch boxes, sort controls, analytics
searchParams page propNoYesFilters and pagination that change content
connection()NoYesRoutes that are per-request anyway

With Cache Components enabled, the useSearchParams reference adds one detail: the boundary is client-rendered only when the rest of the route is prerendered. If any component on the route reads request data such as cookies(), Next.js renders the boundary on the server at request time with the real search params.

Does this matter for crawlers?

It matters for any crawler that reads the HTML without running JavaScript. Google's JavaScript SEO basics say Googlebot queues pages for rendering and runs JavaScript in an evergreen Chromium, so Google can usually see the client-rendered content after that step, while the same page still calls server-side rendering or pre-rendering "a great idea" because not all bots run JavaScript. In Vercel and MERJ's December 2024 measurement, none of the major AI crawlers it tracked executed JavaScript, as covered in do AI crawlers run JavaScript?. For them, a page-level boundary means the page reads as its fallback. Keeping the boundary small removes that barrier; it does not decide whether an assistant uses or cites the page.

Frequently asked questions

Why does my page work in next dev but fail in next build?

In development, routes are rendered on demand, so useSearchParams does not suspend. During a production build, a static page that calls it from a Client Component needs a Suspense boundary, or prerendering fails with the Missing Suspense boundary error.

Is wrapping the whole page in Suspense a valid fix?

It passes the build, but the prerendered HTML then contains only the fallback. Wrap the smallest component that reads the query instead, so the rest of the page is real HTML.

Can I still disable missingSuspenseWithCSRBailout?

The Next.js docs say the option was only available in version 14.x. In later versions you need to fix the code with one of the documented approaches.

Does a loading.js file count as the Suspense boundary?

Yes. Next.js wraps page.js in loading.js as a Suspense boundary, so if nothing closer wraps the hook, the whole page is client-rendered and the HTML holds only the loading UI.

Should I use the searchParams prop or useSearchParams?

Use the searchParams prop when the query changes the content, such as filters or pagination, so the server renders the right content. Use useSearchParams in a small wrapped component when the query only drives UI like a sort control.

Next step

After moving the boundary, run the free check on the affected URL to see whether its main text is in the raw HTML. For a site with many query-driven routes, a full-site audit covers up to 500 pages and comes with a PDF of evidence and prioritized fixes.

Filed under Rendering and content. Topics: nextjs, react, rendering, raw-html, troubleshooting