Next.js 16 Migration Guide: Fixing the Silent Breakages

What breaks silently when you upgrade to Next.js 16?

Four changes ship with no build error and no runtime exception: middleware.ts is ignored until you rename it to proxy.ts, single-argument revalidateTag serves stale data, caching is now opt-in so formerly static routes go dynamic, and params became a Promise so property access returns undefined in plain JavaScript. Everything compiles. Everything deploys. The bugs show up as wrong behavior, not red text.

Version context first, because it matters for what you are upgrading into: Next.js 16 went GA on October 21, 2025, 16.2 shipped on March 18, 2026 with roughly 400% faster dev startup, and 16.3 has been in canary since June 4, 2026.

Here is the table I wish I had before I started:

// proxy.ts (was middleware.ts)
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'

export default function proxy(request: NextRequest) {
  const session = request.cookies.get('session')
  if (!session && request.nextUrl.pathname.startsWith('/dashboard')) {
    return NextResponse.redirect(new URL('/login', request.url))
  }
  return NextResponse.next()
}

export const config = { matcher: '/dashboard/:path*' }

The mental shift: in 15 you fought the framework to make things dynamic; in 16 you declare what is cacheable and everything else is dynamic by default. My rule on the SaaS was simple. Public, shared, tolerant of minutes of staleness: cache it. Authenticated or money-related: do not.

What breaks when Turbopack becomes the default build?

Turbopack is the default for both dev and production builds in Next.js 16, and your webpack() config in next.config is ignored. The tell is this exact line in your build output: Webpack is configured while Turbopack is not, which may cause problems. Anything that depended on a custom loader breaks next, usually SVGR, with Module not found: Can't resolve errors or SVGs importing as URLs instead of components.

The fix is to port loaders to turbopack.rules:

// next.config.ts
const nextConfig = {
  turbopack: {
    rules: {
      '*.svg': {
        loaders: ['@svgr/webpack'],
        as: '*.js',
      },
    },
  },
}

export default nextConfig

If a plugin has no Turbopack equivalent yet, next build --webpack is the escape hatch, but treat it as temporary. The payoff is real: on my machine, dev cold start dropped from about 7.5s to under 2s after 16.2, and the production build went from 2m40s to a bit over a minute. That alone justified the migration for me.

Which changes does the codemod handle, and which are manual?

Run npx @next/codemod@canary upgrade latest first; it reliably handles the syntactic changes and none of the semantic ones. On my codebase it caught every async params/searchParams rewrite in TypeScript files, the import renames, and the config key moves. That is the easy half.

What it cannot do for you:

• Decide what should be cached. The opt-in caching audit is judgment work, route by route.


• Fix revalidateTag semantics. It will not choose between updateTag and revalidateTag(tag, 'max') because that depends on your UX.


• Validate your proxy.ts logic. The rename is trivial; confirming your matchers and auth still behave is not.


• Port webpack loaders. turbopack.rules needs a human who knows why each loader existed.

A loud failure costs you an afternoon. A silent failure costs you a week, because you spend the first six days not knowing it exists.

How long does a Next.js 16 migration take on a production app?

About 14.5 hours for my reputation SaaS: roughly 38 routes, 11 Server Actions, two cron jobs, one developer. Here is the actual breakdown, so you can budget against your own route count:

1. Read the upgrade guide, audit dependencies for Turbopack support: 1.5 h


2. Run the codemod, review the diff: 1 h


3. Fix async params leftovers in plain JS utility files the codemod missed: 2 h


4. Rename middleware.ts to proxy.ts, remove edge runtime assumptions: 1 h


5. Sweep every revalidateTag call, convert to updateTag where actions need fresh reads: 1.5 h


6. Route-by-route cache audit, adding 'use cache', cacheLife, and cacheTag: 4 h


7. Turbopack build fixes (SVGR, one Sass quirk): 1.5 h


8. Staging deploy with route-by-route verification of cache behavior and auth: 2 h

Should you wait for Next.js 16.3?

No. Migrate to 16.2 now; it shipped on March 18, 2026, has had almost three months of patch releases, and the dev startup improvement is worth the effort by itself. 16.3 has been in canary since June 4, 2026 and is incremental, not corrective. There is no breaking change on the horizon that would invalidate work you do today.

My verdict after doing it on a revenue-generating app: Next.js 16 is worth migrating to for the dev-server speed alone, but do it behind a staging deploy with route-by-route cache verification, because the failures are correctness bugs, not crashes. Nothing will page you. Your error tracker stays green while users see stale data and your middleware does nothing. Every greenfield build in my MVP development ↗ work starts on 16.2 now, and it is the default across my web development ↗ client projects, but I will not upgrade an existing production app without that verification pass.

Key takeaways

• Four Next.js 16 changes break apps with zero errors: the proxy.ts rename, deprecated single-arg revalidateTag, opt-in caching, and async params.


• middleware.ts is silently ignored: rename it to proxy.ts, and note it runs on the Node.js runtime only since edge support was removed.


• Caching is now opt-in: routes that were static in 15 go dynamic in 16, so watch TTFB and database load, not error logs.


• The codemod handles syntax, not semantics: async params get rewritten for you; cache decisions and revalidation behavior do not.


• Budget by route count: my 38-route production SaaS took about 14.5 hours, and the route-by-route cache audit was the largest single step at 4 hours.