Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Next.js 16 Upgrade: Async Params, proxy.ts, and Turbopack Build Breaks

The codemod gets you most of the way; the rest is async request APIs, a webpack config Turbopack refuses, and a renamed middleware file that silently stops running.

~4 min readNext.js
#Next.js#Migration#Turbopack#App Router
3D illustration of a Next.js version cube passing an upgrade gate with proxy and turbopack nodes

Introduction & Quick Summary

Symptom. After bumping to Next.js 16 the build stops on errors that did not exist on 15: Route "/blog/[slug]" used "params.slug" directly. "params" is a Promise and must be unwrapped with "await" or React.use(), a failure about a webpack configuration under Turbopack, The "middleware" file convention is deprecated. Please use "proxy" instead, or Type error: Property 'params' does not exist on type '{ children?: ReactNode }'. Some projects build cleanly and then crash at request time with Cannot read properties of undefined (reading 'slug').

Cause. Next.js 16 finished three migrations that 15 only warned about. Synchronous access to request APIs (params, searchParams, cookies(), headers(), draftMode()) is removed. Turbopack became the default bundler for both next dev and next build, and a project that still carries a webpack config makes the build fail deliberately. middleware.ts became proxy.ts and runs on Node.js only. Smaller breaks catch people too: every parallel route slot needs its own default.js, and next lint was removed.

Fix. Run the upgrade codemod (npx @next/codemod@canary upgrade latest), then the async request API codemod (npx @next/codemod@canary next-async-request-api .). Codemods do not finish the job: they cannot convert a params type annotation, they comment out what they cannot prove safe, and they do not migrate webpack loaders with no Turbopack equivalent. The reliable sequence is codemod, next typegen, then fix the remaining UnsafeUnwrapped markers by hand.

Core Mechanics, Signatures & Reproducible Setup

A Next.js 15 page could read params.slug directly because the framework wrapped params in a thenable proxy that resolved synchronously. Next.js 16 removed that proxy: the props are genuine Promises, so the same code produces undefined and the error surfaces where the value is used — a stray params.slug three levels down looks like a routing bug.

Reproduce the upgrade on a scratch project rather than your production app:

bash
npx create-next-app@latest next16-upgrade --ts --app --no-tailwind --no-eslint npx next --version # must print 16.x
tsx
// app/blog/[slug]/page.tsx — Next.js 15 style, breaks on 16 export default function Page({ params }: { params: { slug: string } }) { return <h1>{params.slug}</h1>; }
bash
npm run build # Route "/blog/[slug]" used "params.slug" directly — params is a Promise

The corrected form uses the generated PageProps helper, which keeps the route's param names typed:

tsx
// after: async component, awaited params, typed by route export default async function Page(props: PageProps<'/blog/[slug]'>) { const { slug } = await props.params; const { q } = await props.searchParams; return <h1>{slug} / {q ?? ''}</h1>; }
bash
npx next typegen # writes .next/types: PageProps, LayoutProps, RouteContext

The same rules apply to cookies(), headers(), and draftMode(): const token = (await cookies()).get('session')?.value.

Client components cannot await, so they unwrap with React's use():

tsx
'use client'; import { use } from 'react'; export default function ClientPage({ params }: { params: Promise<{ slug: string }> }) { const { slug } = use(params); // render-time only; throws in an event handler return <span>{slug}</span>; }

Prefer awaiting in a server component and passing the resolved value down: the client tree stays simple and no suspending client boundary appears during hydration.

Key Comparison Table

Change in Next.js 16What breaksMigration
Async request APIs enforcedparams.x, searchParams.q, cookies().get()await in server components, use() in client components, npx next typegen
Turbopack default for dev and buildBuild fails when a webpack config existsnext build --webpack, or migrate to turbopack.rules
middleware.ts → proxy.tsMiddleware silently not running; edge runtime configRename file and export, Node runtime only
Parallel routes need default.jsBuild error for every slot without oneAdd default.js returning null
Cache Components (cacheComponents)dynamic, revalidate, fetchCache exports error once enabledReplace with use cache, cacheLife, cacheTag
revalidateTag requires a profilerevalidateTag('posts') loses stale-while-revalidaterevalidateTag('posts', 'max'), or updateTag
Node.js / TypeScript minimumsNode 18 and TS 4.5 runners failNode 20.9+, TypeScript 5.1+

Practical Edge Cases, Error Fixes & Deep Dive Code Examples

1. The webpack config that fails the build

Error: Webpack is configured while Turbopack is not, which may cause problems. The build refuses to run because a webpack config was found — deliberately, so it cannot be silently ignored.

js
// next.config.js — before module.exports = { webpack: (config) => { config.module.rules.push({ test: /\.svg$/, use: '@svgr/webpack' }); return config; }, };
js
// Option A: keep webpack for production -> "build": "next build --webpack" // Option B: migrate the loader to Turbopack rules module.exports = { turbopack: { rules: { '*.svg': { loaders: ['@svgr/webpack'], as: '*.js' }, }, }, };

If you never wrote a webpack key yourself, a plugin added it. next build --webpack is the safe rollback; do not stay there long, because Turbopack is where 16's build performance work lands.

2. Middleware that stops running after the rename

ts
// proxy.ts — Node.js runtime, same signature import { NextResponse, type NextRequest } from 'next/server'; export function proxy(request: NextRequest) { const token = request.cookies.get('session'); if (!token && request.nextUrl.pathname.startsWith('/app')) { return NextResponse.redirect(new URL('/login', request.url)); } return NextResponse.next(); } export const config = { matcher: ['/app/:path*'] };

Two traps. Renaming the file but leaving export function middleware produces a proxy file with no proxy, and every request passes through. And proxy.ts cannot use the edge runtime: if the middleware relied on export const runtime = 'edge', either keep middleware.ts (deprecated but functional) or move the logic to Node. Config flags followed the rename — skipMiddlewareUrlNormalize is now skipProxyUrlNormalize, and a stale key is ignored without an error.

3. Parallel route slots without default.js

Builds fail when a route has a @slot segment with no default. Return null to keep the previous behaviour:

tsx
// app/@modal/default.tsx — required for every parallel slot in 16 export default function Default() { return null; }

Calling notFound() instead makes a hard navigation to the route 404 rather than render the slot empty — pick by what the slot means. A slot without a default breaks the build before any request is served.

4. Cache Components: the three exports that now error

ts
// app/blog/page.tsx — errors once cacheComponents: true export const dynamic = 'force-dynamic'; export const revalidate = 60; export const fetchCache = 'force-no-store';
tsx
// after: cache what you choose, at the function level import { cacheLife, cacheTag } from 'next/cache'; async function listPosts() { 'use cache'; cacheLife('minutes'); cacheTag('posts'); return db.post.findMany({ orderBy: { publishedAt: 'desc' } }); }

With cacheComponents: true, data fetching is dynamic by default and use cache marks what to cache; the route segment configs above are rejected because they describe the previous model. Do not enable cacheComponents just to finish an upgrade — it is a caching redesign.

5. revalidateTag needed a second argument, and updateTag is new

ts
revalidateTag('posts'); // Next.js 15 revalidateTag('posts', 'max'); // Next.js 16: stale-while-revalidate needs a profile
ts
// read-your-own-writes, Server Actions only 'use server'; import { updateTag } from 'next/cache'; export async function createPost(formData: FormData) { await db.post.create({ data: { title: String(formData.get('title')) } }); updateTag('posts'); // next request waits for fresh data }

updateTag throws outside a Server Action; a Route Handler or webhook must use revalidateTag with a profile. One argument still compiles in some 16 minors but loses the stale-while-revalidate semantics — a page that updates a minute late in production and immediately in dev.

Common Compilation/Runtime Mistakes & Version Gotchas

SymptomCauseFix
params.slug is undefined at runtime, no build errorRead without await, value used laterconst { slug } = await params
use(params) throws "Invalid hook call"Called in a non-component functionUnwrap in the component body
Types missing after codemodCodemod comments out params typesnpx next typegen, use PageProps<'/route'>
Build fails on webpack configTurbopack default--webpack or migrate to turbopack.rules
Middleware not appliedFile renamed, export name notexport function proxy
Redirect loops after renameProxied path matched its own rewriteNarrow config.matcher
404 on a parallel routeMissing default.jsAdd one per slot
revalidateTag no longer invalidatesMissing cache profilerevalidateTag(tag, 'max')

Two gotchas worth a comment in the PR: the Next.js 15 compatibility proxy for request APIs is gone entirely, so a long-lived branch that relied on the sync path returns undefined the moment the lockfile moves; and Turbopack's default applies to next build, so a broken webpack plugin surfaces in CI rather than on a laptop. Keep engines: { node: '>=20.9' } so a Node 18 runner fails at install instead of at build.

For the mechanical parts, the JSON formatter reads RSC payloads, the text diff tool compares generated .next/types, and the YAML converter covers the CI pipeline that still runs next lint. Keep --webpack as the rollback flag and verify next build and next start separately — 16 catches most breaks at build time, but async-params failures appear only at request time.

Try matching browser tools

All tools

Small utilities that fit Next.js work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Next.js guides

More in Next.js

All Next.js guides

The guides filed next to this one in Next.js, in library order.