Support custom HTTP Status Code for Server Components

[devjiwonchoi]

Previous Proposal

Goals

Manage custom statusCode with Server Components in App Router which was an available option in Page Router.
I'm assuming that the most use cases will be error handling.

Handling statusCode in Page Router Server Components

export async function getServerSideProps() {
  try {
    const res = await fetch('https://...');
    const data = await response.json();

    // Customize the response status based on conditions
    const statusCode = response.status !== 200 ? response.status : 404;

    return {
      props: {
        data,
        statusCode,
      },
    };
  } catch (error) {
    return {
      props: {
        data: null,
        statusCode: 500,
      },
    };
  }
}

Suggestion - Pass customized status

import { notFound, setStatus } from 'next/navigation'
// other imports...

async function fetchUser(id) {
  const res = await fetch(`https://...`)
  if (!res.ok) return { status: res.status } // or customized status
  const data = res.json()
  return { status: 200, ...data }
}

export default async function Profile({ params }) {
  const user = await fetchUser(params.id)
  const { status } = user
 
  if (status === 404) notFound()

  // the status code will be most likely 400~500 but should not trigger the Error Boundary
  // and able to return custom components
  if (status === 401) {
    setStatus(status) // or add fallback option?
    return (<NotAuthorized />)
  }
  // ...
}

Reference

• Page Router - Response Helpers

Background

Duplicate requests served on the Discussions community.

#50149 #50383 #50906 #52378 #52796

UPDATE - 21SEP2023

Due to the concept of Streaming, the initial proposal cannot be resolved as @timneutkens has mentioned in #53225 (comment).

Therefore as @icyJoseph has suggested in #53225 (reply in thread), prefetching & setting the status before streaming seems to be a better approach.

New Proposal - prefetchStatus

Basic Usage

type Props = {
  params: { id: string }
  searchParams: { [key: string]: string | string[] | undefined }
}

export async function prefetchStatus({
  params,
  searchParams,
}: Props): Promise<{ status: number }> {
  // fetch to get status
  const response = await fetch(`https://.../${params.id}`)

  // return status
  return { status: response.status }
}

Custom Status Code

export async function prefetchStatus() {
  try {
    const response = await fetch(`https://...`)
    const data = await response.json()

    if (!data.isAdmin) return { status: 401 }
    if (data.isGone) return { status: 410 }
    // ...

    return { status: response.status }
  } catch (error) {
    // ...
    return { status: 500 }
  }
}

Caution ⚠️

Requires a custom fallback in order to not be caught on the Error/NotFound Boundary.

import NotAuthorized from '@components/ui'

export async function prefetchStatus() {
// ...
}

export default function Home() {
  const response = await fetch(`https://...`)
  const data = await response.json()

  if (response.status === 401) return <NotAuthorized />

  return // ...
}

Suggestion - Use with Route Handlers

// app/api/.../route.ts
import { NextResponse } from 'next/server'

export async function GET() {
  try {
    const response = await fetch(`https://...`)
    const data = await response.json()

    if (!data.isAdmin) return NextResponse.json({ data }, { status: 401 })
    // ...

    return NextResponse.json({ data })
  } catch (error) {
    // ...
    return NextResponse.json({ error }, { status: 503 })
  }
}

// app/page.tsx
import { NotAuthorized, ServiceUnavailable } from '@components/ui'

export async function prefetchStatus() {
  const response = await fetch(`https://...`)
  return { status: response.status }
}

export default function Home() {
  const response = await fetch(`https://...`)
  const data = await response.json()

  if (response.status === 401) return <NotAuthorized />
  if (response.status === 503) return <ServiceUnavailable />
  return // ...
}

Background

Although Status Codes have stated that the status codes don't affect SEO;

This does not affect SEO.

feels like an irony to me that Learn Next.js do suggests some status codes that are meaningful in SEO context.

There are many status codes, but only a handful are meaningful in an SEO context.

Reference

• Loading UI and Streaming
• Learn Next.js - What are HTTP Status Codes?
• generateMetadata function

Background

Duplicate requests served on the Discussions community.

#50149 #50383 #50906 #52378 #52796

[moroshko]

@devjiwonchoi setStatus would be great!

[timneutkens]

While I understand the request. It seems there is a misunderstanding about when streaming starts and how that relates to the status code and your code. This proposal can't work because of limitations with streaming, specifically you can't set the status code after the headers have been sent and the stream has started.

At the point where the Profile component in the example runs the headers have already been sent and the stream has been started. This means that you can't change the status code / headers at that point. What we do for notFound() / redirect() when they are called when the stream has started is adding meta tags recommended by Google for these cases.

TLDR: because of streaming rendering and the preinitialization (preamble part of the request) in React you can't modify the status / headers, that's also why you can't set cookies / set headers during server components rendering.

[Libron]

At the moment only workaround is to:

• create /app/404/page.tsx
• in your dynamic page redirect to /404
• in middleware.tsx do condition check for /404 pathname and set 404 status.

I still would like to see some better way handle headers or pass data to middleware.

Could you please share code snippet of middleware ?

[switz]

This has been updated in the documentation to:

Next.js will return a 200 HTTP status code for streamed responses, and 404 for non-streamed responses.

@leerob If this is the case, then can we have a way to set custom status code for non-streamed responses? Some (many?) of us are not using streaming and therefore could take advantage of this feature.

[Israeltheminer]

Having 200 status code for page not found is essentially wrong. It hurts SEO and breaks E2E tests.

Another possible workaround is to create a catch-all route [...not_found]/page.tsx and call notFound() from next/navigation inside the component. This explicitly triggers the 404 logic, even in dynamic routes, without relying on status code manipulation during rendering.

[maslowivan]

What we do for notFound() / redirect() when they are called when the stream has started is adding meta tags recommended by Google for these cases.

@timneutkens Google recommends 410 GONE for the pages need to be excluded from the search indexes, read this discussion, it already has a lot of replies from other developers who work with SEO on expert level. Why can't you implement the same functions like notFound but for other status codes at least? Pardon for pushing

[c0b41]

someone already sent this pull request for 410 #78706, but they probably never gonna merge this. just move your codebase to another framework

[ludwighogstrom]

Hi! Thanks for giving this a go!

I created the #50383 discussion.

The setStatus sort of solves my problem. I see some problems with the suggestion though.

The notFound function is basically a function that throws an error and breaks out of the normal render. It feels a bit hard for the user to understand why the setStatus and notFound works in different ways.

Server components could also be nested. A fetch call could be triggered in a RSC further down (also consider working with multiple fetch in different server components), then it gets hard to solve how to use the setStatus in combination with what's going to be rendered / conflicting status code.

I think it feels more logical to have a serverError function (where you pass in a status code argument) that works in the same way as notFound, i.e. it stops the normal render and server renders the "error" page. Then the error page would need to be able to access status code to render different things.

[mthmcalixto]

I was breaking my head the other day, precisely because of setStatus

[JurajKavka]

"Next.js will also return a 404 HTTP status code." Next returns HTTP 404 only when it is raised from root page.tsx... If it is raised from any leaf Next renders custom 404 page but returns 200. SSR renders and returns loading page to client. Could someone explain me why? It that because haders are already sent?

[ludwighogstrom]

Looks like that if you are looking at @timneutkens answer #53225 (comment)

TLDR: because of streaming rendering and the preinitialization (preamble part of the request) in React you can't modify the status / headers, that's also why you can't set cookies / set headers during server components rendering.

But we already have the notFound function that breaks out of normal render and changes the status code to 404. Don't know if the status code only changes to 404 when used in the root? Feels like the discussion kind of states that but it's not documented here https://nextjs.org/docs/app/api-reference/functions/not-found

Should(?) be possible to change the notFound function to accept a status code argument (4xx range) and use that instead of the 404 that is set now.

Would also like to have a similar function to notFound where you set the status code (in the 5xx range) and that the user ends up on the error page when you use it. Feel like it's too limited to only have 500 status when something goes wrong. For example see #50383

[JurajKavka]

while your route segment does NOT contain file loading.tsx, streaming will not start and notFount() returns HTTP 404 as expected, redirect function returns 307 or 308 as expected. When I add loading.tsx, this behavior is gone (because we are in streaming environment) a function returns HTTP 200. This is what is not clear from documentation.

PS: I'm calling notFound() from generateMetadata() and I would expect that it is called before any streaming starts... but seems it is not true.

[abd2561024]

Hi there, any updates of this issue?

[JurajKavka]

@traviswimer yes, exactly. Result of generateMetadata() function is sent to the browser before any streaming starts with any status codes.

[gnoff]

Hi folks, generateMetadata will not always block the stream. That isn't part of it's API and relying on it is relying on an underlying implementation detail. In the future we will sometimes delay sending metadata so we can get visual content to the user sooner.

[JurajKavka]

OK I'm worry about SEO a lot. I just need proper 404 because it is waste of crawl budget when robot get 200. This is simply not enough: <meta name="robots" content="noindex" />.

In case of 200 I need full HTML content for the robots to index. I think I will not use loader.js to completely overcome streaming or I just stuck in pages router.

From the docs:

[traviswimer]

I haven't figured out why, but I'm getting a 200 response even when using notfound() in generateMetadata(). I guess there is already some condition where this doesn't force a 404. (my guess is something in my middleware file, but I have no idea)

I really like what NextJS is doing with the app router, but after using it for a little while, I'm not sure it should even be considered production-ready.

All software has bugs, but v13 has been out of beta close to a year (I think), and it still contains bugs with no workaround that break fundamental http/browser functionality. As much as I like the direction it's going, it really seems like it should still be in beta.

I'm currently only using Next for a small project where the noindex meta tag is acceptable enough for now, but I no longer plan to use the app router in future projects. It's unfortunate, but I'm now evaluating whether to switch to the pages router or use an entirely different framework.

[JurajKavka]

It is a while I was working on Next13 project but what worked for me on specific minor version must not work on different one. I faced issues with things that changed in between minor versions in the past.

You are true It is not working now. It worked in Next 13.3 but stopped working in 13.4. You must delete loading.tsx file from your route directory. I'm not sure what is hapening with deleting loading.tsx but probably it disables streaming completely.

In my main project I'm still in Next 12 with pages router. I'm integrating third party advertising system and also SEO is everything there. Integrating third party things is not fun. I need complete control over some index.html teplate and <meta> tags in <head>. Everything was vanished with app router. I don't care about RSC, streaming and stuff. I just need framework that is up to date with its dependencies in time and do the job. For example Next13 app router had no way how to respond with permanent redirect in summer when I started. They added it few months later. I spend many unproductive hours with issues like that.

[maslowivan]

404 is just the one example of the codes what can be used to report the NOT FOUND error to the googlebot. For example, what if I need the 410 GONE code? With the next.js sounds impossible at the moment... (And yes, we use it in production, is not just my imagination)

What if the user params are wrong, instead of sort=price he passed sort=test and I would like to send the status code 400 for this or even 403, so hacker knows I see his actions

[v1adko]

I have the same issue, we need a 410 support and using app router in production, very unpleasantly surprised it's not possible to do.

[v1adko]

Hey @studentIvan, maybe our approach could be applicable
#53225 (comment)

[cnunciato]

Looking at the code, a gone() variant of this would seem like a pretty reasonable addition to me:

next.js/packages/next/src/client/components/not-found.ts

Lines 19 to 24 in eb6867f

	export function notFound(): never {
	// eslint-disable-next-line no-throw-literal
	const error = new Error(NOT_FOUND_ERROR_CODE)
	;(error as NotFoundError).digest = NOT_FOUND_ERROR_CODE
	throw error
	}

[maslowivan]

@v1adko yes we have CDN, not Fastly though but Cloudflare. And yes we solve it now using the CDN...

[prademak]

We are facing the same issue. We use NextJS in production and are relying on status codes in our (Akamai) CDN to determine what responses can be cached and when to resort to failover.

(see https://techdocs.akamai.com/property-mgr/docs/cache-http-err-responses and https://techdocs.akamai.com/property-mgr/docs/site-failover)

[suleymangezsat]

When is setStatus development planned for? I haven't seen a pull request yet. Or should we go back to pages directory?

[ddehen]

Will it even be implemented? There seems to be not an awful lot of feedback from the devs about this. Our team decided not to wait for the setStatus and reverted our whole application back to the page router for now. We weren't able to get a CDN stale cache working without any decent status codes. We are shocked such important functionality can go missing from one release to the other.

[suleymangezsat]

indeed, it's a great feeling to use a server-side framework that limits developers to returning only 404 status code :)

[devjiwonchoi]

Hey everyone, I've been thinking about this and to work along with stream, prefetch and set status before streaming like generateMetadata as stated at #53225 (reply in thread) seems to be the only solution so far.

I've updated the proposal, check it out and please share your thoughts.

[JurajKavka]

or do not use loading.js and you are not starting streaming environment... am i right or not?#53225 (reply in thread)

[devjiwonchoi]

IMO as a developer who develops products for the end users, I would say DX shouldn't go over UX. Status Code don't really matter to the users, most of the time it's for DX and SEO, so I wouldn't agree to limit using streaming or etc.

[traviswimer]

@devjiwonchoi I would argue that SEO is UX. Both in the sense that search engine crawlers are technically users, and because it may negatively effect a normal human user's ability to find your site to even experience it at all.

[simonfyi]

Hi,

Are any updates and/or input required?
Missing the statusCode in App routing is a big issue for many devs to move away from Page routing.

Both from development, server, and SEO perspective it's a major requirement.

[dpnolte]

I've created a PR so that we at least have 500s in case of errors before streaming: #56236 (review)

After this PR, there could be at least 404s (which is already there with notFound()) and 500s as response statuses.

I'm hoping that one of Vercel team members can take a look on how to proceed?

[MartinWebDev]

Would be great to see something moving forward in this regard, even if it's a plugin that needs to be installed separately.
We have a use case for status code 410 on dynamic routes (after checking a cms for content) and it seems that's simply not supported in the app router like we've done it in the pages router. So if it'll never be supported the same way, then we'll never be able to fully migrate off the pages router.

[v1adko]

Hey @MartinWebDev, maybe our approach could be applicable for your use case as well
#53225 (comment)

[luanmm]

I'm missing something or really there is no way to get (using "app dir") the http status code in the "error.js" client-side component page?

Currently, I'm stuck on this, which I used to think that should be something simple in any framework/server (at least it is something very trivial in other stacks).

My scenario: I have some roles and a check for users that could access a page or not. Sometimes, if the user access a page that does not have permission, I need to throw an error (passing the "403" as a property, for instance) that changes the "error.js" interface to show the specific situation (that is a "Forbidden" page and not a "Server error").

Any thoughts?

[vks-brussell]

Yep, I was doing a similar thing with the response object which is not writable in next13 appDir. I too am waiting to be able to handle this issue.

[v1adko]

Not sure if it fits your case, but our approach #53225 (comment) allows to get both the app dir and custom status codes with certain minor tradeoffs

[v1adko]

For anyone who's looking for potential solutions our approach could be valuable.

So we have a need to respond with 410 status codes when user-generated content was removed from the website or has expired due to inactivity/unpaid accounts.

What worked for us is to set the status code via next middleware by making an additional HEAD request to the API and then leveraging CDN (Fastly in our case, but I'm sure there should be similar functionality on others)

Not ideal due to second request, but HEAD is lighter and you can optimize with caching per your need. A viable workaround but I'd love this type of thing to be available in a framework that's advertising to be the best SSR solution out there, or at least be way more explicit about this type of breaking/missing features.

Middleware code:

export async function middleware(request: NextRequest) {
  const response = NextResponse.next();
  const pathname = request.nextUrl.pathname;
  
  if (*additional filtering based on pathname*) {
    try {
      const apiResponse = await fetch(`*api-route*`, { method: 'HEAD' });
      response.headers.set('X-Status-Code', String(apiResponse.status));
    } catch (error) {
      logger.error(error);
    }
  }

  return response;
}

export const config = {
  matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)'],
};

Fastly config (custom VCL snippet of type "deliver")

if (resp.http.X-Status-Code) {
  set resp.status = std.strtol(resp.http.X-Status-Code, 10);
}

[astateful]

This is a great idea! My long winded take that I wrote earlier basically boils down to the same thing: leveraging a kind of middleware at the cloud/infrastructure level which reads in a custom header set in the NextJS middleware and in turn uses that to set the appropriate response code.

[masadamsahid]

We definitely need to be able sent a custom status code. It really matters when our Next.js projects need to have a good SEO implementations and deal with the search engine bots properly.

[masadamsahid]

And I think it will be better if we can customize a status code on page.tsx or a non-page server component. If in a non-page server component is impossible, customizing a status code in page.tsx is already more than enough since it is very common implementation to fetch the data needed for a dynamic page in the /[dynamicRoute]/page.tsx.

[felipedeboni]

I agree! Coming up with a workaround to be able to render a nice error message to users and 404 for bots. Basically wrapping all routes with [isBot], when isBot then on generateMetadata if isBot return notFound, otherwise put a title on it...

Kinda crazy that's the only way I found right now.

[necodeus]

We really need this feature...

[fdhani]

Any updates on this issue? We need to a way to send different status codes since we want to handle different error pages for unauthorized, server render errors, or BE errors.

Can't even pass it through an error object since it will be hidden on production

[sunilranaLivspace]

Currently, the app router doesn’t allow sending 404 response codes for non-existent dynamic pages, which is essential for customer-facing websites. Adding this feature would significantly improve handling of these scenarios. Can we have this feature soon?

[lauriskuznecovs]

After spending tons of hours figuring out ways to have correct http status code for 404 and redirects, I tried to find what is actually enabling this Stream rendering for server side.
We had RootLayout and SubLayout files which are really useful, but status codes started to work when I moved i18nProviderClient to some component.

I suggest you also trying to remove / move some stuff away from those Layout files - /src/app/layout.js and /src/app/[locale]/layout.js

In our case for locales we used this - https://next-international.vercel.app/docs

[poznianski]

@timneutkens any news?

[Fonger]

I our use case, we need custom dynamic 404 page.
We have to show why the post was deleted like violation of what forum rules in the 404 page.

Currently, notFound() is the only way to respond 404 as HTTP status code.
However, not-found.tsx can't receive any params and data from page because we can only know the 404 reason at page level.

The only workaround is to use client component and refetch data again at client so we can know the 404 reason, which is not optimal.

If I can manually set status code at page level, then I can render custom not found page directly in the original page and achieve this.

[zoe-ttt]

To back up on the above and to add a few more uses cases:

• We want to be able to return a 410 instead of a 404 where a product existed, and for the user we want to show alternatives. Additionally, we want search engines to understand it’s Gone not Not Found.
• We have certain legal requirements to some pages that can vary, we need to be able to set 451 Unavailable For Legal Reasons.

[arshseraphic]

Do we have any actual solution of this problem?

[quarhodron]

As your docs says:

Since the response headers have already been sent to the client, the status code of the response cannot be updated.

I understand the technical ground of this.

But if I am correct, the response headers are sent to the client before page server component code executes only in case when there is a loading.js file.

Let's me illustrate my considerations with the code.
I have a dynamic app page with the path app/article/[id] and the following code:

export default async function Article({ params }: { params: Params }) {
    const { id } = await params;

    await sleep(3000); // imitates fetching of article data

    if (id === '206') {
        return notFound(); // returns 404 HTTP status code
    }

    if (id === '207') {
        return permanentRedirect('/article/208'); // returns 308 HTTP status code
    }

    if (id === '215') {
        throw new Error('failed to fetch article with id 215'); // returns 500 HTTP status code
    }

    return (
        <div className={styles.root}>
            <h2>This is the article title for article with id: {id}</h2>
            <div>Article content...</div>
        </div>
    );
}

As I said I don't have any loading.js file and when I call notFound() I get the expected 404 status code, for permanentRedirect() I get expected 308 status code and for uncaught error I get 500 status code. So, apparently before starting sending stream response to the client, the page code is executed and somewhere in Next.js internals headers are set.

So my question is: why can't I set headers in page server component when there is no loading.js file?

[Israeltheminer]

[yanghoxom]

@Israeltheminer the main issue is change the status code

[virtual-designer]

Sad to see even something basic like this isn't possible. I ended up creating a custom Apache module mod_proxy_nextjs that proxies requests to an upstream Next.js server and checks for <meta name="nextjs:status"> tags in (X)HTML responses, and then sets the response code accordingly. It isn't the perfect way, but unfortunately there's no other option.

[FeldrinH]

Honestly, it boggles my mind that next.js can't support a feature that practically every other web framework of the last 20 years has had.

[ppiwo]

I don't think this should be marked as answered.

My team has been using the App Router in production for over a year and a half and this remains one of the most frustrating limitations in the framework. It’s a real pain point that still hasn’t been addressed.

I understand that on Vercel, the frontend and CDN layers are tightly integrated, but for self-hosted deployments, this creates major issues. When a page needs to return a specific HTTP status like 503, there's no reliable way to do so using the App Router. This isn't just an edge case. CDNs and reverse proxies depend on response headers, not HTML content, to make caching decisions. Without the ability to set proper status codes and headers we are flying blind.

At the very least, there should be a way to disable the streaming response behavior so we can manage response headers in a normal Response object, or some supported API to let us set status codes from within a page or layout.

This is a massive architectural gap that is being overlooked especially for teams running Next.js in a self hosted enviornment.

[alexleach]

Agreed. I shelved a major project I'd started in next.js entirely for this reason and went looking for alternative mobile-first frameworks, eventually landing on [Expo](https://expo.dev/).

…

________________________________ From: Patrick Piwowarczyk ***@***.***> Sent: 10 June 2025 23:53 To: vercel/next.js ***@***.***> Cc: ALB.Leach ***@***.***>; Comment ***@***.***> Subject: Re: [vercel/next.js] Support custom `HTTP Status Code` for Server Components (Discussion #53225) How is this marked as answered? My team has been using the App Router in production for over a year and a half and this remains one of the most frustrating limitations in the framework. It’s a real pain point that still hasn’t been addressed. I understand that on Vercel, the frontend and CDN layers are tightly coupled and abstracted, but for self-hosted deployments, this creates major issues. When a page needs to return a specific HTTP status like 503, there's no reliable way to do so using the App Router. This isn't just an edge case, CDNs and reverse proxies depend on response headers, not HTML content, to make caching decisions. Without the ability to set proper status codes and headers from a server-rendered page, we are flying blind. At the very least, there should be a way to disable the streaming response behavior so we can manage response headers in a normal Response object, or some supported API to let us set status codes from within a page or layout. This is a massive architectural gap that is being overlooked — especially for teams running Next.js in custom, non-Vercel environments. — Reply to this email directly, view it on GitHub<#53225 (comment)>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/AAC3ZLKQJINW3TQX2TIYYKD3C4ZTDAVCNFSM6AAAAAA2ZBJMDOVHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTGNBSGUZDSNI>. You are receiving this because you commented.Message ID: ***@***.***>