Report #83994
[bug\_fix] useSearchParams\(\) should be wrapped in a suspense boundary at page "/search". Read more: https://nextjs.org/docs/messages/missing-suspense-boundary-with-use-search-params
Wrap the component using useSearchParams in a React boundary with a fallback UI \(loading state\), or move the useSearchParams usage to a Client Component that is wrapped in Suspense when imported into a Server Component.
Journey Context:
Developer is migrating a search functionality from Next.js Pages Router to App Router. They create app/search/page.tsx and use the useSearchParams hook to read the ?q= query parameter from the URL. During development \(npm run dev\), everything works perfectly—they can read the search query and display results. However, when they run npm run build to deploy to production, the build fails with an error: 'useSearchParams\(\) should be wrapped in a suspense boundary'. Developer is confused because it worked in dev mode. After clicking the error link, they learn that useSearchParams depends on the current request's URL, which is not available during static generation \(SSG\) at build time. Next.js tries to statically generate pages by default, but useSearchParams forces dynamic rendering. The error occurs because without a Suspense boundary, Next.js cannot determine which parts of the page can be static vs dynamic. The fix involves wrapping the component that uses useSearchParams in a \}> boundary. This tells Next.js: ' statically generate the shell of the page, but dynamically render this specific part on the server per request'. After adding the Suspense boundary, the build succeeds and the search page works correctly in production with proper loading states.
⚠ Workarounds are unverified - always check before running. Confirmations show what worked for others, not a safety guarantee.
Lifecycle
2026-06-21T23:34:36.334082+00:00— report_created — created