next.js: useSearchParams() should not need to be wrapped in a suspense boundary

Link to the code that reproduces this issue

https://codesandbox.io/p/devbox/nameless-cookies-go8s7s

To Reproduce

  1. Write a page that calls useSearchParams from next/navigation
  2. Make it a client component by adding “use client” at the top
  3. run npm run build
  4. observe error useSearchParams() should be wrapped in a suspense boundary at page "/test". Read more: https://nextjs.org/docs/messages/missing-suspense-with-csr-bailout

Current vs. Expected behavior

  1. The documentation associated with this error is no longer accurate- the linked page suggests to disable the error by adding the experimental feature missingSuspenseWithCSRBailout to next.config.js. This option does not work, and will cause the build to error out saying that feature/flag doesn’t exist.
  2. I don’t see why useSearchParams is any different WRT suspense than any other client function like useState. I don’t need suspense for them, and I don’t see why I should need suspense for useSearchParams
  3. This is not a problem in development- it neither gives an error nor has incorrect behavior.

Provide environment information

Operating System:
  Platform: darwin
  Arch: arm64
  Version: Darwin Kernel Version 24.1.0: Thu Oct 10 21:02:26 PDT 2024; root:xnu-11215.41.3~2/RELEASE_ARM64_T8122
  Available memory (MB): 16384
  Available CPU cores: 8
Binaries:
  Node: 20.17.0
  npm: 10.8.2
  Yarn: 1.22.22
  pnpm: 9.15.0
Relevant Packages:
  next: 15.1.3 // Latest available version is detected (15.1.3).
  eslint-config-next: 15.1.3
  react: 19.0.0
  react-dom: 19.0.0
  typescript: 5.7.2
Next.js Config:
  output: N/A

Which area(s) are affected? (Select all that apply)

Not sure, Documentation

Which stage(s) are affected? (Select all that apply)

next build (local)

Additional context

The linked codesandbox is on the latest canary, and the issue still appears.

About this issue

  • Original URL
  • State: open
  • Created 2 years ago
  • Reactions: 7
  • Comments: 16 (5 by maintainers)

Most upvoted comments

And, sorry but I just ran into this constraint again, why does it complain about a Suspense boundary for a component that is marked with ‘use client’, as in it will get rendered client side anyway?

Also while it’s clear that static pages can’t be generated while using useSearchParams, it doesn’t make any sense why we can not have normal Server Side Rendering with search params. The params 100% get delivered to the server with the request and it can just render the page, nothing prevents it except the current implementation. Forcing client-side rendering doesn’t make sense at all.

In my case our website uses query parameter ?lang=en to switch languages so we would need to wrap our whole website in Suspense. So SSR not possible with Next.js, basically.

I would like to join this discussion because I am encountering this error on a page that is marked as 'use client'. Referring to the documentation, there is no opt-in. The page is marked as a client-rendered page.

Thus, my only option is to disable this check, I think because it is being triggered even though I know that my whole page is client-side rendered.

Further, what other option do I have on an app that is using the export output type to pass a search parameter to another page, for example? Only other thing that comes to mind is local/session storage, which feels ‘odd’.

Any hints how to implement it correctly? Thank you!

Should be a prop you could pass into useSearchParams to have it return empty arrays and null for values during the server pass.

const searchParams = useSearchParams({static: true});

const tag = searchParams.get("tag"); // null on first pass -> my-tag on hydration pass

Even the type of searchParams.get() contains null, so we’re already forced to handle this case.

Update! It took me longer than I’d like to admit, but eventually tunneled the issue into being our Navbar on the layout level which needed to be wrapped in a suspense as it had useSearchParams() used within it.

Didn’t realize that would break all the pages with that, but now is working as intended.

me too i am having the same issue…even after wrapping my component with <Suspense>. …i am just about to downgrade back to nextjs 14…nextjs 15 might not yet be that so stable …i just like the react compiler as it optimizes my animations

No worries, it is important to refine the concepts and arguments, perhaps after all, more documentation is needed, who knows.

I personally, try to avoid using useSearchParams unless, my component does actually need to render, based off the search params, but I see that it is common, for devs to invoke the hook, to then use the values returned within an event listener, or within an effect, that doesn’t depend on the value, but needs it, tracking is often the case. window.location.search does the trick in those cases.

This is but a matter of pre-rendering, vs on-demand. next build runs in your build environment, and has no request, no server, nada, so the concept of search params, and other elements otherwise present in a request, are a non-starter. useSearchParams, on a dynamic (on-demand) route, would work just fine, https://nextjs.org/docs/app/api-reference/functions/use-search-params#dynamic-rendering:

If a route is dynamically rendered, useSearchParams will be available on the server during the initial server render of the Client Component.

I guess the tricky thing is that, searchParams at page level, opts into dynamic rendering, implicitly, whereas useSearchParams, keeps static rendering open, at the cost of "suspending" to the client.

An alternative would be the pages router approach, give an empty container, hydrate with the empty container, and immediately, without letting the browser paint, re-render with a “filled” container, but that had also a bunch of caveats, https://nextjs.org/docs/pages/building-your-application/rendering/automatic-static-optimization#how-it-works, and I recall people running into problems as well.