res.status is not a function in a Next.js API endpoint
TypeError: res.status is not a functionShort 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.
Fix it fast
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/*' \) -print2Match what you see, then jump to its fix
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 -r2Fix
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
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/api2Fix
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/helloConfirmed by nextjs.org
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
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