Avoid this frustrating Next.js App Router quirk where `Suspense` forces streaming mode and breaks `notFound()` 404 status codes.

While working with Next.js App Router (v13+), I discovered a frustrating issue: ⁠notFound() doesn't return a proper ⁠404 HTTP status code when ⁠Suspense is anywhere in your rendering path.

Here's what happens:

When Suspense is present, Next.js automatically enables streaming mode
Streaming mode always returns HTTP 200 OK initially
Your 404 status never reaches the client

Why this matters

This isn’t just a theoretical issue. It has real consequences:

SEO: Search engines see 200 OK instead of 404, potentially indexing non-existent pages
Monitoring: Your error tracking won't catch these as 404s
User Experience: Browsers and tools expect proper status codes

The Catch-22 situation

The worst part? Next.js basically forces you into this trap. Want to use useSearchParams? Cool, wrap it in Suspense. Congrats, you just nuked your 404 status codes:

// app/search/page.tsx
'use client'

import { useSearchParams } from 'next/navigation'

export default function SearchPage() {
  const searchParams = useSearchParams()
  const query = searchParams.get('q')
  
  return <div>Searching for: {query}</div>
}

This will fail at build time with:

Error: useSearchParams() should be wrapped in a suspense boundary at page "/search".
Read more: https://nextjs.org/docs/messages/missing-suspense-with-csr-bailout

How to fix this?

Unfortunately, were’re forced to wrap it in Suspense at a page level (page.tsx):

// app/search/page.tsx
import { Suspense } from 'react'
import SearchComponent from './SearchComponent'

export default function SearchPage() {
  return (
    <Suspense fallback={<div>Loading...</div>}>
      <SearchComponent />
    </Suspense>
  )
}

But now you've enabled streaming mode, and any notFound() call in your page will return 200 OK.

Here’s a quick live demo on one of my side projects. It will return a fully rendered not-found.tsx with a HTTP status code 200 instead of 404, because I had to wrap the main layout in Suspense component, due to having global search in the header.

Potential Solutions

There are a few solutions to this issue I’ve tried successfully, though in the end I had to go back to streaming due to convenience.

1. Avoid `Suspense` on 404-critical pages

If possible, structure your pages so critical 404 checks happen outside Suspense boundaries. Doesn’t work if you need useSearchParams or similar hooks at the page level.

2. Use Route Handlers for client state

Instead of useSearchParams, fetch the data through a Route Handler (API route). It’s more complex, requires additional API routes, client-side fetching.

3. Middleware-level 404 checks

Handle 404s at the middleware level before rendering. This adds latency, duplicates validation logic, and is not suitable for all cases (actually, it should be avoided).

4. Conditional suspense based on route

Only use Suspense when absolutely necessary. This adds complex logic and it still doesn’t solve the fundamental issue.

5. Accept the limitation, breathe... and document

Sometimes the best solution is to make peace with the trade-off:

// app/products/[id]/page.tsx
/**
 * NOTE: This page uses Suspense for client components,
 * which means notFound() will return 200 OK due to streaming.
 * 
 * For SEO purposes, we rely on:
 * - proper canonical URLs
 * - Next.js automatically injects noindex meta tag
 * - sitemap exclusions
 */
export default async function ProductPage({ params }: { params: { id: string } }) {
  // ...
}

Note: Next.js automatically injects <meta name="robots" content="noindex" /> when notFound() is called, preventing search engines from indexing these pages.

What’s causing all this?

This issue stems from how HTTP streaming works:

Server starts sending response with 200 OK
Server streams partial HTML
Server encounters notFound()
Too late — headers already sent

Next.js can’t retroactively change the status code once streaming begins.

What Next.js could do

I think Next.js could handle this way better than it does now. There are a few potential solutions I could think of:

Detect 404 before streaming: delay streaming until critical checks complete
Opt-out of streaming: add a flag like export const dynamic = 'no-stream'
Better error boundaries: handle 404s differently in streaming mode
Build-time warnings: alert devs when Suspense might affect 404s (i.e: detect notFound() usage within Suspense boundaries)

Why does it even matter?

This is a fundamental tension in Next.js App Router between:

modern React patterns (Suspense, streaming)
traditional HTTP semantics (status codes)
developer experience (client components)

Until Next.js can provide a better solution, there’s not much we can really do as developers. We can document and monitor, implement above workarounds, or try to avoid this altogether.

This issue is why I’m not a fan of streaming and would prefer the “interactive islands architecture” pattern from frameworks such as Astro.

It makes things not only more difficult to debug, but also tricky to deal with. A HTTP status codes are a critical signal to external services interacting with our content and should not be taken lightly.

References:

How to Fix Next.js notFound() Returning 200 OK with App Router and Suspense

Avoid this frustrating Next.js App Router quirk where `Suspense` forces streaming mode and breaks `notFound()` 404 status codes.

Dec 07, 2025

Here's what happens:

When Suspense is present, Next.js automatically enables streaming mode
Streaming mode always returns HTTP 200 OK initially
Your 404 status never reaches the client

Why this matters

This isn’t just a theoretical issue. It has real consequences:

SEO: Search engines see 200 OK instead of 404, potentially indexing non-existent pages
Monitoring: Your error tracking won't catch these as 404s
User Experience: Browsers and tools expect proper status codes

The Catch-22 situation

The worst part? Next.js basically forces you into this trap. Want to use useSearchParams? Cool, wrap it in Suspense. Congrats, you just nuked your 404 status codes:

// app/search/page.tsx
'use client'

import { useSearchParams } from 'next/navigation'

export default function SearchPage() {
  const searchParams = useSearchParams()
  const query = searchParams.get('q')
  
  return <div>Searching for: {query}</div>
}

This will fail at build time with:

Error: useSearchParams() should be wrapped in a suspense boundary at page "/search".
Read more: https://nextjs.org/docs/messages/missing-suspense-with-csr-bailout

How to fix this?

Unfortunately, were’re forced to wrap it in Suspense at a page level (page.tsx):

// app/search/page.tsx
import { Suspense } from 'react'
import SearchComponent from './SearchComponent'

export default function SearchPage() {
  return (
    <Suspense fallback={<div>Loading...</div>}>
      <SearchComponent />
    </Suspense>
  )
}

But now you've enabled streaming mode, and any notFound() call in your page will return 200 OK.

Potential Solutions

There are a few solutions to this issue I’ve tried successfully, though in the end I had to go back to streaming due to convenience.

1. Avoid `Suspense` on 404-critical pages

If possible, structure your pages so critical 404 checks happen outside Suspense boundaries. Doesn’t work if you need useSearchParams or similar hooks at the page level.

2. Use Route Handlers for client state

Instead of useSearchParams, fetch the data through a Route Handler (API route). It’s more complex, requires additional API routes, client-side fetching.

3. Middleware-level 404 checks

Handle 404s at the middleware level before rendering. This adds latency, duplicates validation logic, and is not suitable for all cases (actually, it should be avoided).

4. Conditional suspense based on route

Only use Suspense when absolutely necessary. This adds complex logic and it still doesn’t solve the fundamental issue.

5. Accept the limitation, breathe... and document

Sometimes the best solution is to make peace with the trade-off:

// app/products/[id]/page.tsx
/**
 * NOTE: This page uses Suspense for client components,
 * which means notFound() will return 200 OK due to streaming.
 * 
 * For SEO purposes, we rely on:
 * - proper canonical URLs
 * - Next.js automatically injects noindex meta tag
 * - sitemap exclusions
 */
export default async function ProductPage({ params }: { params: { id: string } }) {
  // ...
}

Note: Next.js automatically injects <meta name="robots" content="noindex" /> when notFound() is called, preventing search engines from indexing these pages.

What’s causing all this?

This issue stems from how HTTP streaming works:

Server starts sending response with 200 OK
Server streams partial HTML
Server encounters notFound()
Too late — headers already sent

Next.js can’t retroactively change the status code once streaming begins.

What Next.js could do

I think Next.js could handle this way better than it does now. There are a few potential solutions I could think of:

Detect 404 before streaming: delay streaming until critical checks complete
Opt-out of streaming: add a flag like export const dynamic = 'no-stream'
Better error boundaries: handle 404s differently in streaming mode
Build-time warnings: alert devs when Suspense might affect 404s (i.e: detect notFound() usage within Suspense boundaries)

Why does it even matter?

This is a fundamental tension in Next.js App Router between:

modern React patterns (Suspense, streaming)
traditional HTTP semantics (status codes)
developer experience (client components)

Until Next.js can provide a better solution, there’s not much we can really do as developers. We can document and monitor, implement above workarounds, or try to avoid this altogether.

This issue is why I’m not a fan of streaming and would prefer the “interactive islands architecture” pattern from frameworks such as Astro.

References:

How to Fix Next.js notFound() Returning 200 OK with App Router and Suspense

Why this matters

The Catch-22 situation

How to fix this?

Potential Solutions

1. Avoid Suspense on 404-critical pages

2. Use Route Handlers for client state

3. Middleware-level 404 checks

4. Conditional suspense based on route

5. Accept the limitation, breathe... and document

What’s causing all this?

What Next.js could do

Why does it even matter?

How to Fix Next.js notFound() Returning 200 OK with App Router and Suspense

Why this matters

The Catch-22 situation

How to fix this?

Potential Solutions

1. Avoid Suspense on 404-critical pages

2. Use Route Handlers for client state

3. Middleware-level 404 checks

4. Conditional suspense based on route

5. Accept the limitation, breathe... and document

What’s causing all this?

What Next.js could do

Why does it even matter?

1. Avoid `Suspense` on 404-critical pages

1. Avoid `Suspense` on 404-critical pages