Next.js 15 Build Fails: 'params' type mismatch (Promise) on dynamic routes

[rhennessey3]

Link to the code that reproduces this issue

https://github.com/rhennessey3/personal-website-next.git

To Reproduce

Bug Summary: Next.js Build Error on Dynamic Routes

Symptom: The npm run build command consistently failed with a TypeScript error originating from Next.js generated types (e.g., .next/types/app/blog/[slug]/page.ts):

Type error: Type 'YourPagePropsInterface' does not satisfy the constraint 'PageProps'. Types of property 'params' are incompatible. Type '{ slug: string; }' is missing the following properties from type 'Promise<any>': then, catch, finally, [Symbol.toStringTag]

Affected Routes: The error occurred for all dynamic App Router routes using [slug] parameters (/blog/[slug] and /case-studies/[slug]).
Environment: The issue occurred with Next.js v15.2.4, React v19.0.0, and TypeScript v5.8.2.
Diagnosis: Extensive troubleshooting confirmed the error was not caused by:
Incorrect component code structure (props definition, async usage).
Missing or incorrect generateStaticParams.
Sanity client integration or data fetching logic.
Conflicting layout files or adjacent route files.
Custom global type definitions (.d.ts, types.ts).
Corrupted build caches (.next) or dependencies (node_modules).
Specific route path naming (/blog vs /articles). The error persisted even with minimal component code, indicating a problem within the Next.js build/type-generation process itself incorrectly inferring the params prop type as a Promise.
Resolution: Downgrading core dependencies to the latest stable versions of the previous major releases resolved the issue:
next: 14.2.26 (from 15.2.4)
react: 18.x.x (from 19.0.0)
react-dom: 18.x.x (from 19.0.0)
typescript: 5.4.x (from 5.8.2) This required adjusting next.config.ts to next.config.mjs (removing TypeScript syntax) and temporarily removing incompatible font usage (Geist) from the layout, as these features behaved differently in Next.js 14.
Conclusion: The build error was likely caused by a bug or incompatibility within Next.js v15 and/or React v19 related to TypeScript type generation for dynamic routes in the App Router.

Current vs. Expected behavior

Current Behavior:

When running npm run build with Next.js 15.2.4, React 19.0.0, and TypeScript 5.8.2, the build process fails during type checking. The error occurs specifically for dynamic App Router pages (e.g., app/blog/[slug]/page.tsx, app/case-studies/[slug]/page.tsx). The error message indicates a type mismatch where the page component's props (e.g., BlogPostPageProps) do not satisfy an internally generated PageProps constraint. Specifically, the params property is expected to be of type Promise instead of the correct { slug: string } type. This error persists even when the page component is simplified to a minimal synchronous component and generateStaticParams is hardcoded.

Expected Behavior:

The npm run build command should complete successfully without type errors. The Next.js build process should correctly infer or apply the type constraint for the params prop on dynamic App Router pages as an object containing the route parameters (e.g., { slug: string }). The build should succeed for valid page component structures, including both async components fetching data and simpler synchronous components.

Provide environment information

Environment:

Operating System: macOS Sequoia
Node.js Version: >=18.0.0 (as specified in package.json)
npm/Package Manager: npm (version corresponding to Node.js environment)
Browser (if applicable): N/A (Build-time error)
Relevant Package Versions (Problematic):

next: 15.2.4
react: 19.0.0
react-dom: 19.0.0
typescript: 5.8.2
Relevant Package Versions (Working after Downgrade):

next: 14.2.26 (latest v14 at time of testing)
react: 18.x.x
react-dom: 18.x.x
typescript: 5.4.x

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

Dynamic Routes, TypeScript

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

next build (local)

Additional context

No response

[snivels]

Next.js 15 changed how you get params in a server component from the URL. Params have to be a Promise now and you have to await them.

Your code:

interface BlogPostPageProps {
  params: {
    slug: string;
  };
}

// Async Server Component to fetch and render the blog post
export default async function BlogPostPage({ params }: BlogPostPageProps) {
  const { slug } = params;

Needs to change to:

interface BlogPostPageProps {
  params: Promise<{ slug: string }>
}

// Async Server Component to fetch and render the blog post
export default async function BlogPostPage({ params }: BlogPostPageProps) {
  const { slug } = await params;

It has been updated in the documentation.

[husseinraoouf]

@ijjk should be closed, the issue is just about props being a promise in newer versions of NextJs which is already covered in the documentation and blog post

to further help the original poster and future developers coming to this issue i have opened a PR (rhennessey3/personal-website-next#1) in the repo provided in the issue where i upgrade to next 15 and show the required changes to fix the reported issue

[shieldarchives]

I get the same issue. Only now it happens in Client Component files where I begin the file with "use client"

[ardhrubo]

I was facing the same issue in Next.js 15 + React 19 with dynamic routing in my server component at:
src/app/(pages)/courses/[slug]/page.tsx

The build was failing with this type error:

Type '{ params: { slug: string } }' does not satisfy the constraint 'PageProps'.

❌ What I had before (worked in Next.js 14):

interface CourseDetailsPageProps {
  params: { slug: string };
}

export default async function CourseDetailsPage({ params }: CourseDetailsPageProps) {
  const { slug } = params;
  // ...
}

✅ What fixed it in Next.js 15:

interface CourseDetailsPageProps {
  params: Promise<{ slug: string }>;
}

export default async function CourseDetailsPage({ params }: CourseDetailsPageProps) {
  const { slug } = await params;
  // ...
}

Apparently in Next.js 15, params is now passed as a Promise in server components, so you need to update the type and use await.

Hope this helps anyone running into the same confusion!

Anyway the issue should be closed as it's resolved right now.

[MQJacky]

params: Promise<{ lang: enum }>;

if the typing is enum, the build will always error, unless i changed all enums to string only.

any advice?

[t1szelig]

Bump.
I got same error with enum. Is there any solution for this?

Edit by maintainer bot: Comment was automatically minimized because it was considered unhelpful. (If you think this was by mistake, let us know). Please only comment if it adds context to the issue. If you want to express that you have the same problem, use the upvote 👍 on the issue description or subscribe to the issue for updates. Thanks!