Next.js: useSearchParams() Should Be Wrapped in a Suspense Boundary
A static prerender has no query string, so Next needs a Suspense boundary. Where the boundary belongs, why force-dynamic is different, and how to keep search pages indexable.

Introduction & Quick Summary
Symptom. next build fails while prerendering one route, after compiling successfully:
⨯ useSearchParams() should be wrapped in a suspense boundary at page "/search".
Read more: https://nextjs.org/docs/messages/missing-suspense-with-csr-bailout
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.Cause. useSearchParams() returns request-dependent data. During a static prerender there is no request, so Next renders the component with empty params and would bake that empty state into HTML for every visitor. To avoid it, Next requires a Suspense boundary above the component: the fallback is what gets prerendered, and the real params are read on the client after hydration. Without the boundary, next build stops — since Next 14 this is a build failure rather than a warning.
Fix. Put a <Suspense> boundary in the server component (the page) above the client component that calls the hook, and give it a real fallback. export const dynamic = "force-dynamic" also clears the error by removing the prerender entirely, at the cost of server rendering every request. The boundary is usually what you want; force-dynamic is for pages that are personal and unindexable anyway.
Core Mechanics, Signatures & Reproducible Setup
In the App Router, useSearchParams is a client hook. During prerendering, Next collects the page's static shell; a component that reads the URL search string cannot be part of a shell that is identical for all users unless the read is deferred behind a boundary. That is the entire rule: request data must be inside a boundary or outside the static render.
A five-file reproduction:
// app/search/page.tsx (server component)
import SearchBox from "./search-box";
export default function SearchPage() {
return <SearchBox />; // no Suspense -> build error
}// app/search/search-box.tsx (client component)
"use client";
import { useSearchParams } from "next/navigation";
export default function SearchBox() {
const params = useSearchParams();
const q = params.get("q") ?? "";
return <input defaultValue={q} />;
}npx next build
# ⨯ useSearchParams() should be wrapped in a suspense boundary at page "/search".The minimal correction, with the boundary in the server file:
// app/search/page.tsx
import { Suspense } from "react";
import SearchBox from "./search-box";
export default function SearchPage() {
return (
<Suspense fallback={<input disabled placeholder="Loading search…" />}>
<SearchBox />
</Suspense>
);
}The same rule applies to the Pages Router: a page component that calls useSearchParams is prerendered by next build unless it is wrapped. There the fix is to wrap at the page's own render site — often a small <Suspense> inside the page file — or to make the page a client-only render.
Key Comparison Table
| Option | Prerender | SEO | Data available on first paint | Use for |
|---|---|---|---|---|
<Suspense> boundary | Yes, fallback | Yes, fallback HTML | After hydration | Shared pages with filters, tabs, pagination |
export const dynamic = "force-dynamic" | No | Yes, per request | Yes, params on each request | Personal dashboards, anything behind auth |
Read searchParams on the server | Yes | Yes, real content | Yes, in HTML | Search results you want indexed |
await connection() in the page | No | Yes | Yes | Forcing request-time rendering in one component |
window.location in useEffect | Yes | Weak | Only after mount | Avoid; duplicates the hook |
Where the error comes from, by router:
| Router | File that triggers it | Boundary goes in |
|---|---|---|
| App Router | Any client component using useSearchParams | The nearest server component above it |
| Pages Router | The page component itself | Around that component in the same tree |
output: "export" | Any static route with the hook | Suspense only — force-dynamic is not allowed |
Practical Edge Cases, Error Fixes & Deep Dive Code Examples
1. Boundary in the wrong place
Wrapping the component that calls the hook, from inside that same component, does nothing — the hook runs before the boundary can help:
"use client";
import { Suspense } from "react";
import { useSearchParams } from "next/navigation";
function InnerInner() {
return <p>{useSearchParams().get("q")}</p>;
}
export default function SearchBox() {
return (
<Suspense fallback={null}>
<InnerInner /> {/* correct: the hook is in a child of the boundary */}
</Suspense>
);
}The rule is positional: the boundary must be an ancestor of the hook call, and the ancestor must render on the server or at least not call the hook itself.
2. A fallback that reads params fails too
The fallback is what gets prerendered, so it must be request-free. A skeleton that calls useSearchParams reproduces the error one level down, and the stack trace then points at a file inside node_modules, which is the confusing part of this message.
// Wrong
<Suspense fallback={<SearchBox />}>
// Right
<Suspense fallback={<SearchSkeleton rows={10} />}>3. force-dynamic and output: "export"
For a route where every visitor sees different data and nothing should be indexed, opting out of prerendering is legitimate:
// app/dashboard/page.tsx
export const dynamic = "force-dynamic";
export const revalidate = 0;
export default function DashboardPage() {
return <Filters />;
}Two limits. Route segment config exports are read only from server files, so placing export const dynamic in a "use client" file is silently ignored — the error stays. And with output: "export" there is no server to render dynamically, so force-dynamic is rejected at build time (Page ... is missing "generateStaticParams()" or an export error); the Suspense boundary is the only option there.
4. Read params on the server and pass them down
When the page's content depends on the query and should be indexed (search results, category filters), read searchParams in the server component. In Next 15 and later that prop is a Promise:
// app/search/page.tsx
export default async function SearchPage({
searchParams,
}: {
searchParams: Promise<{ q?: string; page?: string }>;
}) {
const { q = "", page = "1" } = await searchParams;
const results = await searchPosts(q, Number(page));
return <ResultList query={q} results={results} />;
}No hook, no boundary, and the HTML contains real rows. A client component that only needs the current value can take it as a prop; only components that change the params need useSearchParams or useRouter.
5. The same page also needs metadata
generateMetadata runs on the server, so it can read the same params without the hook, and it is where the canonical URL belongs:
export async function generateMetadata({ searchParams }: { searchParams: Promise<{ q?: string }> }) {
const { q } = await searchParams;
return {
title: q ? `Results for ${q}` : "Search",
alternates: { canonical: q ? `/search?q=${encodeURIComponent(q)}` : "/search" },
robots: q ? { index: false, follow: true } : undefined,
};
}Search result pages with arbitrary q values are the classic index-bloat trap; noindex on the parameterised variants while keeping the empty page indexable is the usual compromise.
6. Verifying the boundary works
A passing build is not proof that the page behaves correctly. Check what actually got prerendered:
npx next build
npx next start -p 3100
curl -s http://localhost:3100/search | grep -o "Loading search" # fallback in the HTML
curl -s "http://localhost:3100/search?q=redis" | grep -c "redis" # 0 from static HTMLOn a boundary-wrapped page the static HTML contains the fallback and the server log shows a streamed response; the query text appears only after hydration in the browser. If q=redis shows up in the raw HTML, the route is dynamic, which is correct for option 4 and wrong if you expected a static shell.
Common Compilation/Runtime Mistakes & Version Gotchas
- Boundary around the page instead of around the client component. A
Suspenseinlayout.tsxabove the page works, but a boundary in the same file below the hook call does not; check which component actually callsuseSearchParams. - Route segment config in a client file.
export const dynamicin"use client"has no effect; move it topage.tsxor remove the"use client"directive. - Forgetting
searchParamsis a Promise in Next 15+.searchParams.qgivesundefinedand a type error;awaitit, or destructure from the awaited value. useSearchParamsingenerateMetadataor a server component. The hook is client-only; use thesearchParamsprop, which is available in bothpageandgenerateMetadata.dynamic = "force-dynamic"plusoutput: "export". Mutually exclusive; the export build fails later with a message that does not mention the hook at all.- A
revalidatethat resurrects the static path.export const revalidate = 60on a page with the hook keeps it prerendered and the build error returns; the two settings describe different intents. useSearchParamsin a layout. Layouts render once and do not remount on search changes, so the value goes stale; read params in the page and pass them down, or subscribe withusePathnameplus auseEffect.- Testing against
next dev.next devrenders on demand and never hits the missing boundary, so this error appears for the first time in CI or on deploy; runnext buildbefore pushing a page that reads the URL.
Related tools. Paste the URLs from your access log into the URL parser to see which query keys are actually arriving — most of the traffic that breaks a static search page comes from tracking parameters, not from q — and format the searchParams object with the JSON formatter when a nested or repeated key returns an array instead of a string.
Official references
primary documentationThe Next.js documentation that defines the behaviour this guide explains.
Try matching browser tools
All toolsSmall utilities that fit Next.js work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Next.js guides
All Next.js guidesNext.js 16 DynamicServerError: cookies(), headers() and fetchCache
Request-time APIs make a route dynamic, and Next 16 replaced the segment configs with Suspense boundaries and use cache. What to delete and what to wrap.
Next.js Server Actions: Swallowed Redirects and Body Limits
redirect() throws, so a try/catch swallows the navigation; the action body parser has a 1 MB limit; and useActionState cannot hold an Error. Fixes for all three.
Supabase SSR on Next.js: Stale Sessions and Lock Timeouts
The session flips between signed-in and signed-out because the refreshed token is written to a cookie store that no longer exists. Adapter, proxy and lock fixes.
Next.js Standalone in Docker: Missing CSS and sharp Module Errors
output standalone copies server.js only, so /_next/static and public are missing and every page renders unstyled. The image and copy fixes, plus the sharp native binding error.
More in Next.js
All Next.js guidesThe guides filed next to this one in Next.js, in library order.