useSearchParams() should be wrapped in a suspense boundary at page "/search".

Next.js · updated 2026-11-04

Printed by next build while prerendering a static App Router page, followed by "Error occurred prerendering page". Search parameters only exist per request, so a static page that reads them must either render that part on the client inside a Suspense boundary or be rendered per request.

 ⨯ useSearchParams() should be wrapped in a suspense boundary at page "/search". Read more: https://nextjs.org/docs/messages/missing-suspense-with-csr-bailout
    at a (/app/.next/server/chunks/514.js:1:10520)
Error occurred prerendering page "/search". Read more: https://nextjs.org/docs/messages/prerender-error
Export encountered an error on /search/page: /search, exiting the build.

Quick fix

Move the code that calls useSearchParams() into its own Client Component and render it inside <Suspense> with a fallback. The rest of the page stays static. If the whole page depends on the query string, make it dynamic instead: read the searchParams prop in the page (a Server Component) or call await connection() from next/server.

1. Find the component named in the stack that calls useSearchParams() (often a filter bar, search box or pagination).
2. Keep it a Client Component ('use client') and render it as <Suspense fallback={...}><Filters /></Suspense> in the page.
3. If the page should be rendered per request, use the searchParams prop of the page instead of the hook, or await connection() in the page.
4. Run next build locally to confirm the page prerenders (or shows as dynamic) instead of failing.

// app/search/page.tsx (Server Component)
import { Suspense } from 'react';
import { Filters } from './filters'; // 'use client' file that calls useSearchParams()

export default function SearchPage() {
  return (
    <main>
      <h1>Search</h1>
      <Suspense fallback={<p>Loading filters…</p>}>
        <Filters />
      </Suspense>
    </main>
  );
}

Why it happens

Other fixes

• With cacheComponents enabled the same mistake reports a different message that links to /docs/messages/blocking-prerender-client-hook; the fix is the same Suspense boundary.
• export const dynamic = 'force-dynamic' also makes the build pass, but renders the whole page on every request.

Same error, other wording

• Missing Suspense boundary with useSearchParams
• Error occurred prerendering page "/". Read more: https://nextjs.org/docs/messages/prerender-error
• useSearchParams() should be wrapped in a suspense boundary at page "/404".

Related errors

• Dynamic server usage: Route /x couldn't be rendered statically because it used `headers`.
• An error occurred in the Server Components render. The specific message is omitted in...
• Hydration failed because the server rendered HTML didn't match the client. As a result...

More in React and Next.js rendering

• ReferenceError: window is not definedNext.js
• Error: Event handlers cannot be passed to Client Component props.Next.js
• Only plain objects, and a few built-ins, can be passed to Client Components from Server...Next.js
• Route "/orders/[id]" used `params.id`. `params` should be awaited before using its...Next.js
• Error: NEXT_REDIRECTNext.js
• Error: NextRouter was not mounted.Next.js
• Invalid src prop (https://cdn.example.com/p/42.jpg) on `next/image`, hostname...Next.js
• TypeError: Failed to parse URL from /api/ordersNext.js
• Too many re-renders. React limits the number of renders to prevent an infinite loop.Next.js
• You're importing a module that depends on `useState` into a React Server Component...Next.js
• Objects are not valid as a React child (found: object with keys {id, name, total}). If...Next.js
• Element type is invalid: expected a string (for built-in components) or a class/function...Next.js

References: Next.js docs: Missing Suspense boundary with useSearchParams, Next.js docs: useSearchParams