How to return 404 page from api handler?

[adrianbienias]

By default, all non-existing paths (including frontend and API) return the default 404 Next.js page.
It can be customized in pages/404.js file.

It's possible to return that default/customized error page from getServerSideProps by returning

return {
  notFound: true,
}

https://nextjs.org/docs/api-reference/data-fetching/get-server-side-props#notfound

But what about API handlers?

Response helper has no error method. The body has to be sent manually and JSX obviously doesn't work there.
https://nextjs.org/docs/api-routes/response-helpers

I thought about

res.status(404).send("copied and pasted HTML code from JSX 404 error page")

but it's not an ideal solution...

How to send the default Nextjs error page as a response in API handler?

[icyJoseph]

This is an interesting use case.

The API routes could be modelled as an escape hatch to serve different types of content from your Next.js applications. They are not limited to that, but we could think of them like that for this use case.

There's a few implications, first of all, we do not send any of the _document, nor _app, resulting HTML. It follows that no React framework is served either, nor any CSS used by the app. We are effectively decoupled.

To recreate a page we'd need to serve at the very least, the CSS and HTML structure.

I don't think there's a built-in way to accomplish this. From what I know, rewrites won't make it, because they are based on the file system, rather than responses from API routes.

[adrianbienias]

I don't think there's a built-in way to accomplish this

So how is it handled by default?
All unexisting API's routes show 404 Next.js error page as expected.

I'm not sure I'm digging in the right place, but there's something like sendError in API utils

next.js/packages/next/server/api-utils/index.ts

Line 163 in 3052144

export function sendError(

next.js/packages/next/server/api-utils/node.ts

Line 535 in 4cd8b23

sendError(apiRes, err.statusCode, err.message)

[icyJoseph]

Non existing API's are not found by the file system routing, just like any other request, so the 404 page is put in place, but if something is found, then that's another path.

It'd be interesting to find a mechanism to do this though. Odd that it wouldn't be documented. I wonder if that function is used for middleware, or edge-api's.

[adrianbienias]

Ok. My current 2 workarounds:

1. Using rewrites in next.config.js
   https://nextjs.org/docs/api-reference/next.config.js/rewrites

async rewrites() {
  return [
    {
      source: "/api/path/that/should/return/404",
      destination: "/404",
    },
  ]
},

2. More dynamic approach, in API handler

const fetchRes = await fetch(https://your-nextjs.app/404)
const notFoundPage = await fetchRes.text()
return res.status(404).send(notFoundPage)

Fetch response could be cached if top-notch 404 page performance is needed 😉

[icyJoseph]

Right, well case 1, is trivial sort of... as you said before, if the path doesn't exist, the 404 page is shown.

I think the real tricky one is the second case. That is, when a path is found, and the API handler is run, how to load the 404 page. You might not always have access to the absolute URL where you page is loaded, think of a white-label application.

It is a nice hack though, I guess it, if it gets the job done, then it is good enough.

[CMCDragonkai]

I want to know the same thing but for the custom server. Is there a way to deliberately render the 404 page? I tried using render404 but that didn't work, it just hung the app.

[langy]

I'd also like to know how this might be achieved. I'm currently using this function:

import { notFound } from "next/navigation";

export async function GET() {
  return notFound();
}

as my endpoint is only expecting to receive post requests, which are handled correctly using the export async function POST(request: Request) { function.

But this doesn't return the 404 page. It just shows the browser's default 404 page. I'm guessing since this has been unanswered for so long that it isn't actually possible, which sucks.

[lukasvan3l]

I got this to work:

/app/server/api/file.get.ts

export const config = { runtime: 'nodejs' };

export default defineEventHandler(event => {
  setResponseStatus(event, 404);
  return send(event, 'File not found');
});