Maaz Zindani

Loading the index…

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

fetch('/api/...') returns 404 for a route handler in the app folder

Error404 Not Found when calling an /api URL that has a route.ts

Short 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.

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

Fix it fast

  1. 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/null
  2. 2Match what you see, then jump to its fix

    1. 1The fetch URL does not match any folder that contains route.ts.The file has the wrong name or sits in the wrong folderFix
    2. 2The 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. 3A folder holds both page.tsx and route.ts.A page.js sits in the same folder as route.jsFix
    4. 4The response is 405 rather than 404.The export is not a supported HTTP methodFix

What does the error look like?

  • 404 Not Found when calling an /api URL that has a route.ts
  • 405 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 f

2Fix

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/users

Confirmed by nextjs.org

Did this fix it?

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/null

2Fix

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/hello

Confirmed by nextjs.org

Did this fix it?

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.*' | sort

2Fix

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.ts

3Verify

Restart the dev server and call the API URL; it now answers.

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

Confirmed by nextjs.org

Did this fix it?

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.ts

2Fix

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/users

Confirmed by nextjs.org

Did this fix it?

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

Next step

Want this handled for good?

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