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.

[DennieMello]

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.

lso, if the parent components have Suspense or loading.ts, then in production it always returns 200. In development, everything works well and returns 404.

[lauriskuznecovs]

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

[lauriskuznecovs]

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.

[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.

[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.

[studentIvan]

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
	}

[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.

[suleymangezsat]

Hello everyone,

I've come across this discussion on the challenge of setting custom status codes in Next.js, and I wanted to share a solution that I've developed, which might be helpful.

I've created a proxy middleware named NextStatusProxy specifically to address this issue. This middleware allows developers to set custom status codes via meta tags within their Next.js applications. The middleware then intercepts the server responses, extracts the custom status code from the meta tag, and applies it to the response sent to the client. This approach preserves the streaming functionality of Next.js and adds the flexibility of custom status code handling, which is essential for SEO and server-side control.

For more details and to try it out, please visit the project repository: NextStatusProxy middleware on Github.

Feedback and contributions are most welcome!

[devjiwonchoi]

Thank you! Inspired by your work, created an npm module set-status.

[alanaprianto]

hi there, any update for this issue?

[avetisk]

My main issue with this is that we can't have custom 404 pages.

Currently there's only one way to get a proper 404 status is to use /app/not-found.tsx.

But for those who use i18n routes, such as /[lang]/some/path/page.tsx, we want to have custom 404 pages while enjoying features like useParams() to retrieve the language.

While parsing may work to get the language from the URL in not-found.tsx, it's an issue for the components which require the use of useParams().

Currently I'm using /[lang]/[...slug]/page.tsx to solve this, but I can't get a proper 404 status for that page :/

If we could at least get something like resolveRoutes inside the middleware to check if there's a matching route or not, we could manually add the 404 status.

[quiloos39]

In my case, I needed to remove invalid entries from the Google index. To signal their permanent removal, I had to return a custom 410 status code. While I explored other solutions, they weren't ideal for my use case.

So here is solution i came out with.

create new page called /error/page.tsx

and in the middleware level

// middleware.ts
const urlsToBeGone = []; // Populate with URLs to remove or fetch it from cms

const pathname = request.nextUrl.pathname;

if (urlsToBeGone.includes(pathname)) { 
  return NextResponse.rewrite(new URL('/error', request.url), { status: 410 });
} 

Result:

[quiloos39]

I know this wont fill all use cases but in my case it worked. So if we know urls before hand this might be useful for you guys

[aspnetde]

This might be a bit expensive in some scenarios when you have to fetch the data necessary to decide whether or not the request should be "rerouted", but it seems to be the best option for now. Thanks.

[jdevcc]

We also need to return a 410 status code for SEO reasons. The middleware-based solutions above won't work for us due to lack of Node.js runtime support (we self-host so technically middleware runs in Node.js, but I digress)

[peleteiro]

I would like to add another example where beinging able to set the page status code, without throwing an notFound, would make a lot of sense.

On my site I have a search page with searching as you type feature. For sake of SEO, I need to return 404 status when the page has no results. But, since it's a live search and not-found.js does not have access to params and searchParams I cannot do that with Next App Router. (Can I?)

Looking foward for this to be in Next.js.

The url for search is https://www.bibliaonline.com.br/kjv/busca

[JurajKavka]

Don't do that. Indexing search page or rendering it on server is not recommended by any SEO team. It is useless and the second reason are several spam robots or crawlers, they are trying to make misleading or spammy search requests (just inspect your web server logs. We found dozens of request with asian language characters). All that requests hits your database. Try to inspect web server logs and think about to competely remove search page from SSR. It should be just client-side functionality for Your users.

[peleteiro]

Thanks for the insight. You are absolutely right.

[jnm733]

We need too a fine grained management of the HTTP error status codes per page without depending on the middleware

[jdevcc]

@leerob can we please remove the answered tag on this discussion? The original question was updated with a solution that should play nicely with the new streaming architecture.

[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.