Route Handler Context Type Mismatch (`params` as `Promise`)

[pfilipak]

Link to the code that reproduces this issue

https://github.com/pfilipak/nextjs-context-bug-example.git

To Reproduce

Describe the Bug
When creating a dynamic API route (e.g. app/api/employee-shifts/[id]/route.ts), the generated type in .next/types/app/api/employee-shifts/[id]/route.ts expects the context parameter to be:

{ params: Promise<{ id: string }> }

However, according to the Next.js documentation, the correct type should be:

{ params: { id: string } }

This causes the following build error:

Type '{ id: string; }' is missing the following properties from type 'Promise<any>': then, catch, finally, [Symbol.toStringTag]

To Reproduce

1. Create a dynamic API route: app/api/employee-shifts/[id]/route.ts
2. Use the documented handler signature:

   export async function GET(_req: NextRequest, context: { params: { id: string } }) { ... }

3. Run next build
4. Observe the type error referencing .next/types/app/api/employee-shifts/[id]/route.ts

Workaround
Changing the handler to:

export async function GET(_req: NextRequest, context: { params: Promise<{ id: string }> }) {
  const { id } = await context.params;
  // ...
}

allows the build to succeed, but this is not the documented or expected API.

Current vs. Expected behavior

Expected Behavior
The generated types in .next/types should expect params to be an object, not a Promise, matching the documentation and previous Next.js behavior.

Provide environment information

**What version of Next.js are you using?**

next: 15.3.3
typescript: 5.x
react: 19.x
@types/react: 19.x


**What version of Node.js are you using?**

node: 22.14.0

Which area(s) are affected? (Select all that apply)

Route Handlers

Which stage(s) are affected? (Select all that apply)

next build (local)

Additional context

Additional Context

• The error persists even after cleaning .next and node_modules, and reinstalling dependencies.
• The issue only resolves with the workaround above.

[icyJoseph]

Hi,

this was a breaking change for v14 to v15 migrations, the link you shared is 404'ing.

Your workaround is correct:

// app/api/employee-shifts/[id]/route.ts
export async function GET(_req: NextRequest, context: { params: Promise<{ id: string }> }) {
  const { id } = await context.params;
  // ...
}

• https://nextjs.org/docs/app/api-reference/file-conventions/route#dynamic-route-segments

[pfilipak]

Joseph,
Thanks — the link works fine.

Just to confirm, have you already cloned the repository on your local machine? Let me know if you ran into any issues during the setup.

[icyJoseph]

Try it out here, https://stackblitz.com/edit/github-kmjdpvry?file=app%2Fapi%2Femployee-shifts%2F[id]%2Froute.ts

import { NextRequest, NextResponse } from 'next/server';

export async function GET(
  _req: NextRequest,
  context: { params: Promise<{ id: string }> }
) {
  const { id } = await context.params;
  return NextResponse.json({
    id,
    message: 'Hello from dynamic API route!',
  });
}

This is how it has to be. Think of it this way, Next.js is in charge of eventually invoking GET.

What they are telling you is that, when they do call it, they'll pass a params object, that's a Promise. The build step is just ensuring that your function definition aligns with that, otherwise, we know we might be allowing an incorrect build, that could break at runtime.

They have a compatibility layer in v15, so it kind of works in some cases, but the recommendation is to just assume the dynamic promise access like.

[icyJoseph]

@pfilipak do you feel ready to close the issue? Is it all clear?

[pfilipak]

@icyJoseph
I feel ready to close the issue. Everything is clear now. ✅

[github-actions]

This closed issue has been automatically locked because it had no new activity for 2 weeks. If you are running into a similar issue, please create a new issue with the steps to reproduce. Thank you.