Allow returning the not-found page from route handlers

[Vinnl]

Goals

Allowing a route handler to trigger a render of the not-found page.

Non-Goals

Customising the 404 page from the route handler.

Background

Some route handlers with dynamic routes, e.g. /app/[slug]/route.ts, might want to return a 404 for some values of the segment. They can currently do this:

  return new NextResponse(null, { status: 404 });

However, that won't render the not-found page.

Proposal

Support either:

1. calling notFound() in route handlers, or
2. returning a method like NextResponse.notFound(), or
3. some other method of triggering a render of the not-found page from a route handler.

[juliankoehn]

I agree that allowing route handlers to trigger a 404 page render would be very useful, especially for dynamic routes. The current workaround of returning a 404 status without a page render is not ideal.

Of the options proposed, I think notFound() called within route handlers would be the cleanest API. It's easy to read and understand what it does.

Rendering the actual 404 page instead of just returning a status code would also help avoid confusing empty responses in certain situations. For example, in authentication flows using OAuth - triggering a proper 404 would make errors and unexpected states clearer to the user.

Overall this would be a great quality-of-life improvement for developers working with Next.js apps. I'm excited about the possibility of having this functionality added! Let me know if there's anything I can help with to move this proposal forward.

Related

• Errors in generateMetadata are not handled by error.tsx #49925

[sanny-io]

I just ran into this issue as well. My use case is that I'm proxying a file response from an external server, but would like to show a friendly 404 rather than the default browser one.