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.

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:
npx create-next-app@latest next16-upgrade --ts --app --no-tailwind --no-eslint
npx next --version # must print 16.x// 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>;
}npm run build
# Route "/blog/[slug]" used "params.slug" directly — params is a PromiseThe corrected form uses the generated PageProps helper, which keeps the route's param names typed:
// 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>;
}npx next typegen # writes .next/types: PageProps, LayoutProps, RouteContextThe 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():
'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 16 | What breaks | Migration |
|---|---|---|
| Async request APIs enforced | params.x, searchParams.q, cookies().get() | await in server components, use() in client components, npx next typegen |
| Turbopack default for dev and build | Build fails when a webpack config exists | next build --webpack, or migrate to turbopack.rules |
middleware.ts → proxy.ts | Middleware silently not running; edge runtime config | Rename file and export, Node runtime only |
Parallel routes need default.js | Build error for every slot without one | Add default.js returning null |
Cache Components (cacheComponents) | dynamic, revalidate, fetchCache exports error once enabled | Replace with use cache, cacheLife, cacheTag |
revalidateTag requires a profile | revalidateTag('posts') loses stale-while-revalidate | revalidateTag('posts', 'max'), or updateTag |
| Node.js / TypeScript minimums | Node 18 and TS 4.5 runners fail | Node 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.
// next.config.js — before
module.exports = {
webpack: (config) => {
config.module.rules.push({ test: /\.svg$/, use: '@svgr/webpack' });
return config;
},
};// 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
// 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:
// 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
// app/blog/page.tsx — errors once cacheComponents: true
export const dynamic = 'force-dynamic';
export const revalidate = 60;
export const fetchCache = 'force-no-store';// 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
revalidateTag('posts'); // Next.js 15
revalidateTag('posts', 'max'); // Next.js 16: stale-while-revalidate needs a profile// 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
| Symptom | Cause | Fix |
|---|---|---|
params.slug is undefined at runtime, no build error | Read without await, value used later | const { slug } = await params |
use(params) throws "Invalid hook call" | Called in a non-component function | Unwrap in the component body |
| Types missing after codemod | Codemod comments out params types | npx next typegen, use PageProps<'/route'> |
Build fails on webpack config | Turbopack default | --webpack or migrate to turbopack.rules |
| Middleware not applied | File renamed, export name not | export function proxy |
| Redirect loops after rename | Proxied path matched its own rewrite | Narrow config.matcher |
| 404 on a parallel route | Missing default.js | Add one per slot |
revalidateTag no longer invalidates | Missing cache profile | revalidateTag(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 toolsSmall utilities that fit Next.js work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Next.js guides
All Next.js guidesNext.js Hydration Mismatch: Why Server HTML Does Not Match the Client
React never reconciles a hydration mismatch; it re-renders the boundary. The four causes, the diff that finds them, and the patterns that keep the first client render identical to the server's.
Next.js Static Export, Standalone Output, and Docker Deployment
Export has no server, standalone has a pruned one, and the default expects a full install. The three COPY lines that decide whether a container renders CSS.
Next.js Parallel Routes and Intercepting Routes: Slot Layouts and Modals
Named slots render several pages in one layout, and (.) interception makes a click open over the page while a direct link renders the full route. Why every slot needs default.tsx.
Next.js ISR: Route Revalidate, revalidateTag, and On-Demand Invalidation
Two clocks and one trigger: route revalidate seconds, fetch-level tags, and a webhook that calls revalidateTag. A timer is a ceiling on freshness, never a guarantee.
More in Next.js
All Next.js guidesThe guides filed next to this one in Next.js, in library order.