nextjs - 💡(How to fix) Fix Type error: Dynamic API route handler params type mismatch in Next.js App Router [3 comments, 3 participants]

Link to the code that reproduces this issue

https://github.com/LucasEdwa/bug-repo

To Reproduce

1. Clone the reproduction repo: git clone https://github.com/LucasEdwa/bug-repo.git
2. Run npm install
3. Run npm run build
4. Observe the type error about the dynamic API route handler params

Current vs. Expected behavior

Expected: The build should succeed with the documented dynamic API route handler signature. Actual: The build fails with a type error about the params type, expecting Promise<{ id: string }> instead of { id: string }.

Provide environment information

Operating System:
  Platform: darwin (macOS)
  Arch: arm64
  Version: Darwin Kernel Version 23.6.0

Binaries:
  Node: v23.2.0
  npm: 10.x (exact version not available due to PATH issue)

Relevant Packages:
  next: 15.5.2
  react: 19.x
  react-dom: 19.x
  typescript: 5.9.2

Next.js Config:
  output: N/A

Which area(s) are affected?
- App Router
- API Routes

Which stage(s) are affected?
- Build

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

• This issue occurs locally on macOS (Apple Silicon, Node v23.2.0).
• I am not deploying to Vercel or Docker; this is a local development build.
• The error occurs in a fresh Next.js app with the minimal reproduction.
• I have tried both stable and canary versions of Next.js and TypeScript.
• The issue is not browser-specific, as it happens at build time.
• No experimental or advanced Next.js features are enabled.

error =>{ npm run build

[email protected] build next build --turbopack

▲ Next.js 15.5.3 (Turbopack)

Creating an optimized production build ... ✓ Finished writing to disk in 38ms ✓ Compiled successfully in 1605ms Linting and checking validity of types .Failed to compile.

Type error: Type 'typeof import("/Users/lucaseduardo/bug-repo/app/api/route/[id]/route")' does not satisfy the constraint 'RouteHandlerConfig<"/api/route/[id]">'. Types of property 'POST' are incompatible. Type '(request: NextRequest, { params }: { params: { id: string; }; }) => Promise<NextResponse<{ id: string; }>>' is not assignable to type '(request: NextRequest, context: { params: Promise<{ id: string; }>; }) => void | Response | Promise<void | Response>'. Types of parameters '__1' and 'context' are incompatible. Type '{ params: Promise<{ id: string; }>; }' is not assignable to type '{ params: { id: string; }; }'. Types of property 'params' are incompatible. Property 'id' is missing in type 'Promise<{ id: string; }>' but required in type '{ id: string; }'.

Next.js build worker exited with code: 1 and signal: null