Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

A Next.js API endpoint returns 404 Not Found

Error404 Not Found

Short answer

Next.js has two API systems and a 404 usually means a file is in the wrong one. A Pages Router handler must live in pages/api. An App Router handler must be a route.ts file inside app, with named exports such as GET or POST. A pageExtensions setting can also hide the file.

  • Applies to Next.js 15, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    List every file that could define the endpoint, and see which router folder it is in.

    find . -path ./node_modules -prune -o \( -path "*/pages/api/*" -o -name "route.*" \) -print
  2. 2Match what you see, then jump to its fix

    1. 1The file is app/api/hello.ts (or similar) with export default function handler(req, res).A Pages Router style handler is in the app folderFix
    2. 2The file is pages/api/hello/route.ts, so it maps to /api/hello/route and not /api/hello.An App Router style route.ts sits in pages/api, or the folder path is wrongFix
    3. 3The file is in the right place and has the right shape, but its extension is not in pageExtensions.pageExtensions in next.config hides the fileFix

What does the error look like?

  • 404 Not Found
  • GET /api/hello 404

Cause 1 of 3

A Pages Router style handler is in the app folder

1Check

In the App Router, Route Handlers are defined in a file named route, not by any file under api. They use the Web Request and Response APIs.

find app -path "*api*" -type f

2Fix

Rename the file to route.ts in its own folder and export a function named after the HTTP method.

// app/api/hello/route.ts
export async function GET() {
  return Response.json({ message: "Hello World" });
}

3Verify

Request the URL again.

curl -i http://localhost:3000/api/hello

Confirmed by nextjs.org

Did this fix it?

Cause 2 of 3

An App Router style route.ts sits in pages/api, or the folder path is wrong

1Check

In the Pages Router, any file inside pages/api maps to /api/* with the file name as part of the URL. The handler is a default export that takes req and res.

find pages/api -type f

2Fix

Use the Pages shape in pages/api, or move the endpoint to app/api/<name>/route.ts and use the App Router shape.

// pages/api/hello.ts
import type { NextApiRequest, NextApiResponse } from "next";

export default function handler(req: NextApiRequest, res: NextApiResponse) {
  res.status(200).json({ message: "Hello from Next.js!" });
}

3Verify

Request /api/hello.

curl -i http://localhost:3000/api/hello

Confirmed by nextjs.org

Did this fix it?

Cause 3 of 3

pageExtensions in next.config hides the file

1Check

For Pages Router API routes, the pageExtensions setting in next.config applies, so a file with another extension is not treated as a route.

grep -n "pageExtensions" next.config.*

2Fix

Add the extension you use to pageExtensions, or rename the file to one already listed.

// next.config.js
module.exports = {
  pageExtensions: ["ts", "tsx", "js", "jsx"],
};

3Verify

Restart the dev server and request the endpoint.

npm run dev

Confirmed by nextjs.org

Did this fix it?

How do I stop it coming back?

  • Pick one router per endpoint and use its file shape: route.ts exports named methods, pages/api exports a default handler.
  • Check the path-to-URL mapping with curl straight after creating a file.
  • Remember that route params in App Router handlers are a promise in Next.js 15, so await them.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.