Maaz Zindani

Loading the index…

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

Next.js logs an error that params, searchParams, cookies() or headers() must be awaited

Your error

Error: Route "/item/[id]" used `params.id`. `params` should be awaited before using its properties. Learn more: https://nextjs.org/docs/messages/sync-dynamic-apis3 more lines it can show

Fix it fast

Most common cause, 1 of 3

A Server Component or route handler reads params without await

Turn the component or handler into an async function and destructure after awaiting.

Fix
// app/item/[id]/page.tsx
export default async function Page({
  params,
  searchParams,
}: {
  params: Promise<{ id: string }>
  searchParams: Promise<{ q?: string }>
}) {
  const { id } = await params
  const { q } = await searchParams
  return <p>Item {id}, query {q}</p>
}
Did this fix it?
Full steps for this cause: check, fix, verify

Short answer

Since Next.js 15, params, searchParams, cookies(), headers() and draftMode() return Promises. Reading a property straight off them still works in 15 but logs this error, and Next.js 16 removes the synchronous path. Make the page or function async and await the value, use React's use() in a Client Component, or run the next-async-request-api codemod.

  • Applies to Next.js 15.5, React 19, Node.js 24
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Which cause do you have?

Let the official codemod rewrite the easy cases, then search for whatever it marked as needing a manual change.

Run this first
npx @next/codemod@canary next-async-request-api .
grep -rn "@next-codemod-error" app src 2>/dev/null

Then find the line you see in this list and open its fix:

  1. 1A Server Component or route handler reads params without awaitThe error names `params` or `searchParams` and points at a line like params.id in a page, layout or route.ts
  2. 2cookies(), headers() or draftMode() is used like a plain objectThe message says `cookies()` or `headers()` should be awaited before using its value
  3. 3A Client Component receives params as a propThe file starts with 'use client', so it cannot be an async component

What does the error look like?

  • Error: Route "/item/[id]" used `params.id`. `params` should be awaited before using its properties. Learn more: https://nextjs.org/docs/messages/sync-dynamic-apis
  • Error: Route "/item/[id]" used `searchParams.q`. `searchParams` should be awaited before using its properties.
  • Error: Route "/c" used `cookies().get('theme')`. `cookies()` should be awaited before using its value.
  • Error: Route "/c" used `headers().get('user-agent')`. `headers()` should be awaited before using its value.

Cause 1 of 3

A Server Component or route handler reads params without await

You seeThe error names `params` or `searchParams` and points at a line like params.id in a page, layout or route.ts

Check

Open the file in the stack trace. If the component is a plain function that reads params.slug or searchParams.page directly, it is using the old synchronous form that Next.js 15 only keeps for compatibility.

Check
grep -rnE "params\.[a-zA-Z]+|searchParams\.[a-zA-Z]+" app

Fix

Turn the component or handler into an async function and destructure after awaiting. In TypeScript, type the prop as a Promise of the shape you expect.

Fix
// app/item/[id]/page.tsx
export default async function Page({
  params,
  searchParams,
}: {
  params: Promise<{ id: string }>
  searchParams: Promise<{ q?: string }>
}) {
  const { id } = await params
  const { q } = await searchParams
  return <p>Item {id}, query {q}</p>
}

Verify

Reload the route in next dev. The terminal no longer prints the sync-dynamic-apis error for that route.

Verify
curl -s -o /dev/null -w '%{http_code}\n' 'http://localhost:3000/item/42?q=x'

Confirmed by nextjs.org

Did this fix it?

Cause 2 of 3

cookies(), headers() or draftMode() is used like a plain object

You seeThe message says `cookies()` or `headers()` should be awaited before using its value

Check

Look for calls chained directly onto the function, such as cookies().get(...) or headers().get(...). Those functions now hand back a Promise, so the chained call happens on the wrong thing.

Check
grep -rnE "(cookies|headers|draftMode)\(\)\." app src

Fix

Await the function first and keep the result in a variable. The surrounding function has to become async, and so does anything that calls it and needs the value.

Fix
import { cookies, headers } from 'next/headers'

export default async function Page() {
  const cookieStore = await cookies()
  const theme = cookieStore.get('theme')?.value
  const ua = (await headers()).get('user-agent')
  return <p>{theme} {ua}</p>
}

Verify

Request the page with a cookie set and confirm the value renders and the terminal stays quiet.

Verify
curl -s -b theme=dark http://localhost:3000/ | grep -o dark

Confirmed by nextjs.org

Did this fix it?

Cause 3 of 3

A Client Component receives params as a prop

You seeThe file starts with 'use client', so it cannot be an async component

Check

Client Components cannot be async functions. If the component that reads params or searchParams is marked 'use client', await is not an option there.

Check
grep -rln "'use client'" app | xargs grep -ln "params"

Fix

Unwrap the Promise with React's use() hook. Another option is to await in a parent Server Component and pass plain values down.

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

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

Verify

The page renders the id and the browser console shows no warning about params.

Verify
npx next build

Confirmed by nextjs.org

Did this fix it?

How do I stop it coming back?

  • Treat every request-time value as async in new code, even where a synchronous read still happens to work.
  • Run next build in CI so the remaining synchronous reads show up before an upgrade to Next.js 16.
  • Type params and searchParams as Promise<...> so the compiler catches a direct property read.

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:

Next step

Want this handled for good?

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