Maaz Zindani

Loading the index…

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

res.status is not a function in a Next.js API endpoint

ErrorTypeError: res.status is not a function

Short answer

In the App Router a route handler receives a Request and must return a Response. There is no res object, so res.status throws. Rewrite the handler to return Response.json with a status option. The res.status helper exists only in Pages Router API routes under pages/api, where the handler takes req first and res second.

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

Fix it fast

  1. 1Find out which cause you have

    Look at which folder the file is in. app/.../route.ts is a Route Handler; pages/api/... is an API Route. They use different signatures.

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

    1. 1File is app/api/.../route.ts and the function takes (req, res)A Pages-style handler was placed in an App Router route.tsFix
    2. 2File is pages/api/... and the handler is declared as (res, req) or with only one argumentThe Pages API handler has its arguments in the wrong orderFix

What does the error look like?

  • TypeError: res.status is not a function

Cause 1 of 2

A Pages-style handler was placed in an App Router route.ts

1Check

Route Handlers export functions named after HTTP methods. The first argument is a Request, and you return a Response.

grep -n "res\." app/api -r

2Fix

Export a method function and return Response.json with the status in the options.

export async function POST(request: Request) {
  const body = await request.json()
  return Response.json({ received: body }, { status: 201 })
}

3Verify

Call the endpoint and check the status code.

curl -i -X POST http://localhost:3000/api/items -d '{"a":1}' -H 'Content-Type: application/json'

Confirmed by nextjs.org

Did this fix it?

Cause 2 of 2

The Pages API handler has its arguments in the wrong order

1Check

API Routes receive req first and res second. res is a Node.js ServerResponse with Express-like helpers such as res.status and res.json.

grep -rn "export default" pages/api

2Fix

Use the documented signature.

import type { NextApiRequest, NextApiResponse } from 'next'

export default function handler(req: NextApiRequest, res: NextApiResponse) {
  res.status(200).json({ message: 'ok' })
}

3Verify

Request the route and read the JSON.

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

Confirmed by nextjs.org

Did this fix it?

How do I stop it coming back?

  • Pick one router per endpoint and copy examples from the matching docs section.
  • Type handlers (NextApiRequest, NextApiResponse or Request) so the editor flags res on a Route Handler.
  • Await params in dynamic Route Handlers; they are a promise in current versions.

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.