useSearchParams() should be wrapped in a suspense boundary

  • Next.js
  • Vercel

What it means

The page is built ahead of time, but part of it reads the address bar, which only exists when someone visits. Next.js needs that part wrapped in Suspense so the rest can still be built in advance.

Why it happens

  • A client component reads useSearchParams (or usePathname with unknown parts) on a prerendered page.
  • It worked in development and fails in the production build.

How to fix it

  1. Wrap the component that reads the address in <Suspense fallback={…}>.
  2. Keep the wrapped part small, so the rest of the page is still prerendered.

Let your AI find the cause

Paste this into Claude Code, Cursor, Lovable or whichever AI built your app. It looks first and changes nothing until you have read the answer.

My Next.js build fails with 'useSearchParams() should be wrapped in a suspense boundary'. Without changing anything yet, find the components on that page that read the URL, and propose the smallest Suspense boundary around them.