Type error after upgrading: params does not satisfy the PageProps constraint
Type '{ 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.
Fix it fast
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=*.ts2Match what you see, then jump to its fix
- 1
The error points at a page.tsx whose props look like { params: { id: string } }.The page types params as a plain objectFix - 2
The same error, on a page that reads the query string.searchParams is still typed as a plain objectFix - 3
The page starts with 'use client' and reads params directly, or you added async to it.A Client Component page cannot be asyncFix - 4
The error names a route.ts file with a { params: { id: string } } context.The second argument of a route handler is typed the old wayFix
- 1
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.tsx2Fix
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 buildConfirmed by nextjs.org
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.tsx2Fix
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 buildConfirmed by nextjs.org
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.tsx2Fix
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 devConfirmed by nextjs.org
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.ts2Fix
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 --noEmitConfirmed by nextjs.org
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
- TaskvareA task and project-management suite: React on the web, Flutter on mobile, TypeScript underneath.
Related fixes
Web apps
Upgrading to Next.js 16: middleware becomes proxy, and the other things that break
Missing Required default.js for Parallel Route
Next.js 16 renames middleware.ts to proxy.ts and its exported function to proxy.
6 causes, each with a fixWeb apps
Importing useActionState from react fails in a Next.js project
The editor flags useActionState as not exported by react
useActionState exists only in React 19 and later.
4 causes, each with a fixWeb 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 fixWeb apps
TypeScript says a JSX element type has no construct or call signatures
'Promise<Element>' is not a valid JSX element
TypeScript accepts a capitalised JSX tag only when the value is a function component or a class component.
3 causes, each with a fixWeb apps
TypeScript refuses JSX because the jsx option is not set
TS17004: Cannot use JSX unless the '--jsx' flag is provided.
TypeScript compiles JSX only when you name the file with a .tsx extension and enable the jsx compiler option.
2 causes, each with a fixWeb apps
TypeScript rejects a component that returns an array or other non-Element
Its return type 'Element[]' is not a valid JSX element.
TypeScript before 5.1 required every component to return JSX.Element or null, so arrays, strings and Promises were rejected even though React renders them.
2 causes, each with a fix