A Next.js API endpoint returns 404 Not Found
404 Not FoundShort 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.
Fix it fast
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.*" \) -print2Match what you see, then jump to its fix
- 1
The 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
The 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
The 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
- 1
What does the error look like?
404 Not FoundGET /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 f2Fix
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/helloConfirmed by nextjs.org
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 f2Fix
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/helloConfirmed by nextjs.org
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 devConfirmed by nextjs.org
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
Web apps
Apollo Server rejects a request as a potential CSRF
HTTP 400 Bad Request from the GraphQL endpoint
Apollo Server's CSRF prevention is on by default.
3 causes, each with a fixWeb apps
Clerk cannot read its publishable key in a Next.js app
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY is undefined
Clerk reads NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY.
3 causes, each with a fixWeb apps
The shell cannot find create-next-app
command not found: create-next-app
create-next-app is not meant to be installed as a shell command.
2 causes, each with a fixWeb apps
ESLint fails with: Cannot find module 'next/babel'
ESLint stops on the first file with a Babel or parser error instead of listing lint results
next/babel is a Babel preset that ships inside the next package.
3 causes, each with a fixWeb apps
Firebase Auth says the API key is not valid
Firebase: Error (auth/api-key-not-valid.-please-pass-a-valid-api-key.)
The apiKey your app sends is either empty, wrong, or blocked.
4 causes, each with a fixWeb apps
Jest fails with SyntaxError: Unexpected token when testing a Next.js component
Jest failed to parse a file.
Jest only understands plain JavaScript until a transform and a few file mappings tell it more.
3 causes, each with a fix