Maaz Zindani

Loading the index…

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

Type error after upgrading: params does not satisfy the PageProps constraint

ErrorType '{ params: { id: string; }; }' does not satisfy the constraint 'PageProps'

Short answer

Since Next.js 15, params and searchParams are Promises, not plain objects. A type such as { params: { id: string } } no longer matches what Next.js generates, so the build fails. Type params as Promise<{ id: string }> and await it in a Server Component, or call React's use() in a Client Component.

  • Applies to Next.js 15, Next.js 16, React 19, TypeScript 5
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Find every file that reads params or searchParams. Each one is a place where the old synchronous type may still be in use.

    grep -rn -E "params|searchParams" app src/app --include=*.tsx --include=*.ts
  2. 2Match what you see, then jump to its fix

    1. 1The error points at a page.tsx whose props look like { params: { id: string } }.The page types params as a plain objectFix
    2. 2The same error, on a page that reads the query string.searchParams is still typed as a plain objectFix
    3. 3The page starts with 'use client' and reads params directly, or you added async to it.A Client Component page cannot be asyncFix
    4. 4The error names a route.ts file with a { params: { id: string } } context.The second argument of a route handler is typed the old wayFix

What does the error look like?

  • Type '{ params: { id: string; }; }' does not satisfy the constraint 'PageProps'

Cause 1 of 4

The page types params as a plain object

1Check

In Next.js 14 and earlier, params was a synchronous prop. In 15 it is a promise, so the old object type is incompatible with it.

grep -rn "params: {" app src/app --include=page.tsx

2Fix

Type params as a Promise, make the component async and await it before reading the value. Next.js can also type the props from the route string with the PageProps helper.

// app/blog/[id]/page.tsx
export default async function Page({
  params,
}: {
  params: Promise<{ id: string }>
}) {
  const { id } = await params
  return <div>Post {id}</div>
}

// or let Next.js generate the type from the route
export default async function Page(props: PageProps<'/blog/[id]'>) {
  const { id } = await props.params
  return <div>Post {id}</div>
}

3Verify

Run a type check, then a production build.

npx tsc --noEmit
npx next build

Confirmed by nextjs.org

Did this fix it?

Cause 2 of 4

searchParams is still typed as a plain object

1Check

searchParams in page.js became asynchronous in the same release as params, so it needs the same change.

grep -rn "searchParams" app src/app --include=page.tsx

2Fix

Type it as a Promise and await it next to params.

type SearchParams = Promise<{ [key: string]: string | string[] | undefined }>

export default async function Page(props: {
  params: Promise<{ slug: string }>
  searchParams: SearchParams
}) {
  const { slug } = await props.params
  const { query } = await props.searchParams
  return <div>{slug} {query}</div>
}

3Verify

The build passes and the query value still reaches the page.

npx next build

Confirmed by nextjs.org

Did this fix it?

Cause 3 of 4

A Client Component page cannot be async

1Check

A page marked 'use client' cannot await. Its params prop is still a promise, so it has to be unwrapped another way.

grep -rln "use client" app src/app --include=page.tsx

2Fix

Unwrap the promise with React's use(). Alternatively, call the useParams hook anywhere inside the Client Component tree.

'use client'
import { use } from 'react'

export default function Page({
  params,
}: {
  params: Promise<{ slug: string }>
}) {
  const { slug } = use(params)
  return <p>{slug}</p>
}

3Verify

Open the page in development and confirm the slug renders.

npm run dev

Confirmed by nextjs.org

Did this fix it?

Cause 4 of 4

The second argument of a route handler is typed the old way

1Check

In route.js, context.params is a promise as well, so the context type and the way you read it both need to change.

grep -rn "params" app --include=route.ts

2Fix

Type params as a Promise and await it, or use the global RouteContext helper. The helper is generated by next dev, next build or next typegen.

// app/users/[id]/route.ts
import type { NextRequest } from 'next/server'

export async function GET(
  _req: NextRequest,
  ctx: RouteContext<'/users/[id]'>
) {
  const { id } = await ctx.params
  return Response.json({ id })
}

3Verify

Generate the types, then type check.

npx next typegen
npx tsc --noEmit

Confirmed by nextjs.org

Did this fix it?

How do I stop it coming back?

  • After a major upgrade, run the official upgrade codemod first and read every spot it flags instead of casting around the error.
  • Use the PageProps, LayoutProps and RouteContext helpers so the type follows the folder name.
  • Run tsc --noEmit in CI so a wrong props type fails the pull request, not the deploy.
  • Keep @types/react and @types/react-dom on the versions the upgrade guide asks for.

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

TypeScript rejects a useRef ref passed to an input element

Type 'MutableRefObject<HTMLInputElement | undefined>' is not assignable to type 'LegacyRef<HTMLInputElement> | undefined'

The ref prop on a DOM element expects an object whose current value is the element or null.

2 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.