Custom error code for notFound page in appDir

[astateful]

Goals

1. Flexibility of defining custom error codes when triggering notFound() in appDir
2. Feature parity with pages dir in NextJs 13 error handling
3. Improve SEO by returning a 410 instead of a 404
4. By law it may be required to return a 430 code (for example in Germany some provinces require website operators to block all gambling related shops and therefore a 430 must be returned).

Non-Goals

No response

Background

An example of a use case is SEO, in which a statically generated page that has been indexed by a search engine and then subsequently removed would return a 410 Gone response instead of a 404 Not Found. This would allow crawlers to interpret the status code in a way that not does not punish the resulting website. I am sure there are other examples too.

Prior art would be that NextJS 13 pages dir already supports returning custom error codes via the Error page getInitialProps.

Error.getInitialProps = ({ res, err }) => { const statusCode = res ? res.statusCode : err ? err.statusCode : 404; return { statusCode }; };

Right now in nextJS 13+appDir we simply call the error page directly from within another page and pass the desired status code.

Nextjs 13 + appDir currently does NOT support this functionality which is a blocker for us in adopting appDir since we are an SEO driven company and small details such as this one matter a great deal to us.

Proposal

I would suggest when the notFound function is called that the desired status code should passed in as a parameter to the notFound function. For example to generate a not found page with 410 code:

if (valueIsEmpty) notFound(410)

notFound() is typically called where the generated data is being used so it makes sense to set the status code at same location.

[logan-jobzmall]

Have this exact same issue. Most of the responses have been "410 gone" isn't widely used, etc etc. But for SEO purposes on dynamic websites and managing crawl budget, it is important to let crawlers know to never come back to a web page.

[astateful]

Hi Login, thank you so much for contributing to the discussion! Just curious, where did you receive these responses? Was it on the NextJS repo itself, in relation to some issues?

One idea I had in solving this issue was using a managed service such as Netlify, in which for every route one can specify what the resulting error code should be in a netlify-specific Yaml file. Granted, this does not solve the problem directly in code (which is the best fix), however it does mean that its possible to have a solution. For us this status code issue is a deal breaker.

[devjiwonchoi]

@logan-jobzmall @astateful
Posted #53225 before working on it, can you confirm if this is what you are requesting?

[astateful]

@devjiwonchoi Yes but I found a solution, posted it here. I will post it there as well.

[ludwighogstrom]

This feature is much needed! Created this discussion a while ago #50383

... had an idea about a serverError function where you can specify status code (not limited to 4xx).

[astateful]

Hi Ludwig,

Apologies that I did not see your discussion already, otherwise I would have contributed there as well. The situation is mitigated somewhat due to fact that NextResponse.rewrite supports a second parameter for sending a custom status code. Although it is broken and there is already an issue for it: #50155.

But still something should be supported within code and your serverError idea sounds like a great start! It would be similar to calling notFound(), or?

[ludwighogstrom]

Hi Ludwig,

Apologies that I did not see your discussion already, otherwise I would have contributed there as well. The situation is mitigated somewhat due to fact that NextResponse.rewrite supports a second parameter for sending a custom status code. Although it is broken and there is already an issue for it: #50155.

But still something should be supported within code and your serverError idea sounds like a great start! It would be similar to calling notFound(), or?

Hi, no worries! Yes, a separate function for server errors (5xx status codes) that works in a similar way to notFound feels like a logical approach.

I hope this can get some traction!

[astateful]

Hey everyone,

After some research I was basically able to solve the problem. But it definitely involves some infrastructure topics that are beyond the scope of NextJS. Essentially, the discussion is about the notFound() function being able to handle custom error codes. But rather than rely on the logic of triggering the notFound during the rendering process (which as I understand starts the streaming rendering which makes breaking out difficult), it may be more advantageous to pre-compute a routing table. During the pre-computation of the routes it is then possible to store the associated status code for each route, and then in middleware, see if the incoming route is in your route table, and if it is, redirect/rewrite based on that status code in the table to the appropriate NextJS fallback page.

Now when we talk about having custom status codes in middleware, we realize with #50155 that this issue still has not been fixed. Furthermore, accessing the route table from within middleware may be a super slow process as well, since NextJS does not cache fetch requests in middleware. And one cannot establish a direct DB connection in middleware either. So what to do now?

Here is where the infrastructure aspect comes in. There is a service called FlightControl which enables one to deploy NextJS builds to AWS, while giving control of the entire AWS deploy to the user. Consequently, we were able to deploy our app to AWS via FlightControl, and then using a Lambda edge function (triggered via Cloudfront request viewer), do a lookup of our routing table that we store in DynamoDB (basically a massively scalable KV store), and rewrite or redirect the url to the appropriate fallback page with the proper status code. So for example if someone visits /missingPage, it is redirected to NextJS rendered page /fallback/410 with status code 410. We pre-generate fallback pages for as many status codes as we need to support.

Essentially, we rebuilt what is provided by the Vercel Edge Config, and then some, since we can now set custom status codes in middleware. Note that AWS is not necessary to solve this, you just need an infrastructure that allows to define edge functions one level higher than NextJS and which allows fast access to your computed route table. So Cloudflare workers would also be an option here if you do not wish to use AWS or FlightControl. You still need fast access to the route table however.

We are also able to easily update the route table through standard AWS DynamoDB, to allow for easy addition or removal of pages. And via messaging we can update the route table the instant a page in our DB changes. So in the end reframing this problem as one to be solved outside of NextJS helped us a lot. And its even more efficient, since we do not need to try to render pages and see if they fail. We use the same routing table when statically generating all the pages so we do not need to trigger a notFound() anywhere in our codebase.

Sorry for long winded take. Hope this helps someone.

[FeldrinH]

This sounds cool, but at the same time it feels kind of absurd that such a complex solution that depends on external infrastructure is necessary for what seems like a fairly simple, self contained and common problem.

[alihaddadkar]

This is such a helpful idea. Looking forward to seeing it implemented.