Next.js: useSearchParams() is missing a Suspense boundary

What it means in plain English

useSearchParams() reads the query string. Next.js says that calling it without a Suspense boundary opts the whole page into client-side rendering, so the page can stay blank until the browser JavaScript loads.

Likely causes

• A search box or a ?code= handler calls useSearchParams() directly in the page.
• The call sits in the root layout, so every route is affected.
• The AI disabled the check in next.config instead of wrapping the component.

How to fix it, step by step

1. Find the call. Next.js says next build --debug-prerender prints a fuller stack trace with source maps.
2. Move useSearchParams() into a small child component and wrap that child in <Suspense>. Next.js's example keeps the static shell and avoids turning the whole page into client rendering.
3. If the page should wait for the request instead, a Server Component can call await connection() from next/server. Next.js also documents passing the searchParams prop into a client child and unwrapping it with React use() inside Suspense.
4. Do not set missingSuspenseWithCSRBailout: false. Next.js says that switch is only for version 14, they do not recommend it, and it will be removed.

How to check it worked

• The production build no longer reports a missing Suspense boundary.
• The page paints its shell before the search box finishes, and the query string still shows up in the box.

Sources

• https://nextjs.org/docs/messages/missing-suspense-with-csr-bailout (opens in a new tab)