vercel / vercel/next.js

useSearchParams() should not need to be wrapped in a suspense boundary

Open
#74,494 25 comments 21 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
JavaScript
Stars
142k
Forks
32.4k
Avg merge
2d 14h
Merged PRs (30d)
351

Description

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.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the useSearchParams entry point from next/navigation and reproduce the behavior with the linked CodeSandbox. Run npm run build on the client-component example and compare the error with the linked missing-suspense-with-csr-bailout documentation. Done means the documented behavior and the build result agree, or the issue has a clearly supported resolution.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, nextjs, react
Domain
build-system, documentation, frontend
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.