next.js/errors/missing-suspense-with-csr-bailout.mdx

---
title: Missing Suspense boundary with useSearchParams
---

## Why This Error Occurred

Reading search parameters through `useSearchParams()` without a Suspense boundary will opt the entire page into client-side rendering. This could cause your page to be blank until the client-side JavaScript has loaded.

## Possible Ways to Fix It

You have a few options depending on your intent:

- To keep the route statically generated, wrap the smallest subtree that calls `useSearchParams()` in `Suspense`, for example you may move its usage into a child Client Component and render that component wrapped with `Suspense`. This preserves the static shell and avoids a full CSR bailout.
- To make the route dynamically rendered, use the [`connection`](/docs/app/api-reference/functions/connection) function in a Server Component (e.g. the Page or a wrapping Layout). This waits for an incoming request and excludes everything below from prerendering.

```tsx filename="app/page.tsx" switcher
import { connection } from 'next/server'

export default async function Page() {
  await connection()
  return <div>...</div>
}
```

```jsx filename="app/page.js" switcher
import { connection } from 'next/server'

export default async function Page() {
  await connection()
  return <div>...</div>
}
```

- Before the `connection` API was available setting `export const dynamic = 'force-dynamic'` in a Server Component `page.tsx`, or `layout.tsx`, opted the route into on-demand rendering. Note that setting `dynamic` in a Client Component (`'use client'`) `page.tsx` has no effect.

```tsx filename="app/layout.tsx" switcher
export const dynamic = 'force-dynamic'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return children
}
```

```jsx filename="app/layout.js" switcher
export const dynamic = 'force-dynamic'

export default function RootLayout({ children }) {
  return children
}
```

- Alternatively, a Server Component Page can pass the `searchParams` value down to Client Components. In a Client Component, you can unwrap it with React's `use()` (ensure a surrounding `Suspense` boundary). See [What to use and when](/docs/app/getting-started/layouts-and-pages#what-to-use-and-when).

```tsx filename="app/page.tsx" switcher
import { Suspense } from 'react'
import ClientSearch from './client-search'

export default function Page({
  searchParams,
}: {
  searchParams: Promise<{ q?: string }>
}) {
  return (
    <Suspense fallback={<>...</>}>
      <ClientSearch searchParams={searchParams} />
    </Suspense>
  )
}
```

```tsx filename="app/client-search.tsx" switcher
'use client'

import { use } from 'react'

export default function ClientSearch({
  searchParams,
}: {
  searchParams: Promise<{ q?: string }>
}) {
  const params = use(searchParams)
  return <div>Query: {params.q}</div>
}
```

```jsx filename="app/page.js" switcher
import { Suspense } from 'react'
import ClientSearch from './client-search'

export default function Page({ searchParams }) {
  return (
    <Suspense fallback={<>...</>}>
      <ClientSearch searchParams={searchParams} />
    </Suspense>
  )
}
```

```jsx filename="app/client-search.js" switcher
'use client'

import { use } from 'react'

export default function ClientSearch({ searchParams }) {
  const params = use(searchParams)
  return <div>Query: {params.q}</div>
}
```

- Consider making the Page a Server Component again and isolating Client-only code (that uses `useSearchParams`) into child Client Components.

```tsx filename="app/search.tsx" switcher
'use client'

import { useSearchParams } from 'next/navigation'
import { Suspense } from 'react'

function Search() {
  const searchParams = useSearchParams()

  return <input placeholder="Search..." />
}

export function Searchbar() {
  return (
    // You could have a loading skeleton as the `fallback` too
    <Suspense>
      <Search />
    </Suspense>
  )
}
```

```jsx filename="app/search.js" switcher
'use client'

import { useSearchParams } from 'next/navigation'
import { Suspense } from 'react'

function Search() {
  const searchParams = useSearchParams()

  return <input placeholder="Search..." />
}

export function Searchbar() {
  return (
    // You could have a loading skeleton as the `fallback` too
    <Suspense>
      <Search />
    </Suspense>
  )
}
```

## Disabling

> **Note**: This is only available with Next.js version 14.x. If you're in versions above 14 please fix it with the approach above.

We don't recommend disabling this rule. However, if you need to, you can disable it by setting the `missingSuspenseWithCSRBailout` option to `false` in your `next.config.js`:

```js filename="next.config.js"
module.exports = {
  experimental: {
    missingSuspenseWithCSRBailout: false,
  },
}
```

This configuration option will be removed in a future major version.

## Debugging

If you're having trouble locating where `useSearchParams()` is being used without a Suspense boundary, you can get more detailed stack traces by running:

```bash
next build --debug-prerender
```

This provides unminified stack traces with source maps, making it easier to pinpoint the exact component and route causing the issue.

## Useful Links

- [`useSearchParams`](/docs/app/api-reference/functions/use-search-params)
- [`connection`](/docs/app/api-reference/functions/connection)
- [Debugging prerender errors](/docs/app/api-reference/cli/next#debugging-prerender-errors)