fetch('/api/...') returns 404 for a route handler in the app folder
404 Not Found when calling an /api URL that has a route.tsShort answer
A route handler is only found when a file named route.js or route.ts sits in a folder under app, and the folder names form the URL. Check the path first, then that no page.js shares the folder, that you did not put it in pages/api by habit, and that the exported function name is an HTTP method.
Fix it fast
1Find out which cause you have
List every route handler file. The folders above each one are the URL you must call.
find app src/app -name "route.*" 2>/dev/null2Match what you see, then jump to its fix
- 1
The fetch URL does not match any folder that contains route.ts.The file has the wrong name or sits in the wrong folderFix - 2
The project has both app and pages folders, or the file exports default function handler(req, res).The handler is in pages/api, or uses the Pages Router styleFix - 3
A folder holds both page.tsx and route.ts.A page.js sits in the same folder as route.jsFix - 4
The response is 405 rather than 404.The export is not a supported HTTP methodFix
- 1
What does the error look like?
404 Not Found when calling an /api URL that has a route.ts405 Method Not Allowed
Cause 1 of 4
The file has the wrong name or sits in the wrong folder
1Check
Route Handlers are defined in a route.js or route.ts file inside the app directory. Name any other way (api.ts, index.ts, handler.ts) and Next.js does not treat it as a route.
find app src/app -path "*api*" -type f2Fix
Rename the file to route.ts and put it in the folder chain that matches the URL. The file app/api/users/route.ts answers /api/users.
// app/api/users/route.ts
export async function GET() {
return Response.json({ users: [] })
}3Verify
Call the URL directly while the dev server runs.
curl -i http://localhost:3000/api/usersConfirmed by nextjs.org
Cause 2 of 4
The handler is in pages/api, or uses the Pages Router style
1Check
Route Handlers are only available inside the app directory. They replace API Routes from the pages directory, so you do not combine the two styles in one file.
ls pages/api app/api 2>/dev/null2Fix
Move the code to app/api/<name>/route.ts and replace the default export with a named export per HTTP method that returns a Response.
// before: pages/api/hello.ts
// export default function handler(req, res) { res.status(200).json({ ok: true }) }
// after: app/api/hello/route.ts
export async function GET() {
return Response.json({ ok: true })
}3Verify
Request the route and read the JSON body.
curl -s http://localhost:3000/api/helloConfirmed by nextjs.org
Cause 3 of 4
A page.js sits in the same folder as route.js
1Check
A route.js cannot live at the same route as page.js. Each of them takes over every HTTP verb for that path, so the two conflict.
find app src/app -name 'page.*' -o -name 'route.*' | sort2Fix
Move the handler into its own folder, usually app/api/<name>/, and keep the page where it was.
# invalid
app/items/page.tsx
app/items/route.ts
# valid
app/items/page.tsx
app/api/items/route.ts3Verify
Restart the dev server and call the API URL; it now answers.
curl -i http://localhost:3000/api/itemsConfirmed by nextjs.org
Cause 4 of 4
The export is not a supported HTTP method
1Check
Supported methods are GET, POST, PUT, PATCH, DELETE, HEAD and OPTIONS. If the request uses a method you did not export, Next.js returns 405 Method Not Allowed.
grep -n "export" app/api/users/route.ts2Fix
Export a function named exactly like the method your client sends, in capital letters.
export async function POST(request: Request) {
const body = await request.json()
return Response.json({ received: body })
}3Verify
Send the same method the client uses.
curl -i -X POST -H 'Content-Type: application/json' -d '{"a":1}' http://localhost:3000/api/usersConfirmed by nextjs.org
How do I stop it coming back?
- Keep every API route under app/api so the folder tree mirrors the URLs you call.
- After adding a route.ts, call it once with curl before wiring the client code to it.
- Do not mix pages/api and app/api for the same feature.
- Await params in dynamic route handlers; in Next.js 15 and later it is a promise.
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
AuthUserPoolException: Auth UserPool not configured in a Next.js app
Auth UserPool not configured
The error means an Amplify Auth call ran before Amplify.configure did.
3 causes, each with a fixWeb 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
ESLint says an element in a list is missing its key prop
react/jsx-key
react/jsx-key fires when an element returned from map, Array.from or an array literal has no key.
3 causes, each with a fix