← Blog

Next.js 16 upgrade checklist: every breaking change, the error you'll see, and the fix

By VibeBoot · 2026-11-02

Short on time? The SaaS Starter already has this wired up: $49 one-time, 14-day money-back guarantee.

Upgrading a Next.js 15 app to Next.js 16 is mostly renames and removals, but a few of them fail silently, and coding agents trained on older code keep writing the old version back in. This checklist covers every breaking change in the official upgrade guide, what you'll see when it bites, and the fix. Work through it top to bottom.

Everything below was checked on Nov 2, 2026 against the official Next.js 16 upgrade guide. Both VibeBoot starters already run on Next.js 16.4 with proxy.ts and async params.

The 60-second version

Step 0: run the codemods first

npx @next/codemod@canary upgrade latest

That one command updates next.config for top-level turbopack, moves next lint to the ESLint CLI, renames middleware to proxy, drops the unstable_ prefix from stabilized APIs and removes experimental_ppr.

It does not migrate synchronous request APIs. If your app still reads params or cookies() without await, also run:

npx @next/codemod@canary next-async-request-api .

Then search the diff for UnsafeUnwrapped and codemod error comments. Those are the spots it couldn't fix for you.

If you use Cursor or Claude Code, run npx @next/codemod@canary agents-md too. It points AGENTS.md at the docs bundled with your installed Next.js version, so the agent stops suggesting Next.js 14 patterns. More on that in Next.js 16 writes your AGENTS.md now.

1. Requirements: Node.js 20.9+, TypeScript 5.1+

Node.js 18 is no longer supported. Check your CI image, your Dockerfile and the Node version your host uses. Browser support is now Chrome/Edge/Firefox 111+ and Safari 16.4+. Upgrade @types/react and @types/react-dom along with next, react and react-dom.

2. Async request APIs: the silent one

Next.js 15 made params, searchParams, cookies(), headers() and draftMode() async, but kept a synchronous fallback. Next.js 16 removes the fallback.

The dangerous part is that params.slug on a Promise is just undefined. If your types still say { params: { slug: string } }, TypeScript stays quiet and the page renders "not found".

// Next.js 16
export default async function Page(props: PageProps<"/blog/[slug]">) {
  const { slug } = await props.params;
  const query = await props.searchParams;
  return <h1>{slug}</h1>;
}

Run npx next typegen to get the global PageProps, LayoutProps and RouteContext helpers. The same change applies in layout, route handlers, default, and the opengraph-image, twitter-image, icon and apple-icon files. In image files, id from generateImageMetadata is now a Promise too, and so is id in a sitemap that uses generateSitemaps.

Full fix with the agent prompt: params.slug is undefined (params is a Promise).

3. middleware.ts becomes proxy.ts

Rename the file and the exported function:

mv middleware.ts proxy.ts

export function proxy(request: Request) {}

Two things to watch:

• Proxy runs on Node.js only. The edge runtime isn't supported in proxy, and you can't configure it. If you really need edge, the guide says to keep using middleware for now. Don't blindly rename edge middleware.
• Config flags were renamed too. skipMiddlewareUrlNormalize is now skipProxyUrlNormalize.

With Auth.js v5 the whole file can be export { auth as proxy } from "@/auth". Walkthrough: Auth.js v5 on Next.js 16. Paste your old file into the free middleware.ts → proxy.ts converter to see the diff, or read the deprecation warning fix.

4. Turbopack is now the default

next dev and next build use Turbopack, so you can drop --turbopack from your scripts. If anything adds a webpack config (often a plugin you didn't write), next build fails on purpose. Your options:

• Migrate the config to Turbopack options. experimental.turbopack is now top-level turbopack.
• Keep Webpack for production with next build --webpack.

Two Turbopack differences that break builds: Sass imports with the ~ prefix (@import '~bootstrap/...') need the tilde removed, and client code that imports Node modules fails with Module not found: Can't resolve 'fs'. The right fix for that is to keep Node APIs in server code: Can't resolve 'fs' fix.

5. next lint is gone

next lint is removed, the eslint option in next.config is removed, and next build no longer lints. Replace the script with plain eslint (or Biome) and run it in CI yourself:

npx @next/codemod@canary next-lint-to-eslint-cli .

@next/eslint-plugin-next now defaults to flat config, so move off .eslintrc if you haven't.

6. Caching APIs changed signature

• revalidateTag("posts") is deprecated and a TypeScript error. Use revalidateTag("posts", "max") for stale-while-revalidate.
• For "the user just saved and must see it", use the new updateTag(tag) in a Server Action.
• refresh() from next/cache refreshes the client router from a Server Action.
• cacheLife and cacheTag are stable. Import them without unstable_.
• experimental.ppr, experimental.dynamicIO and experimental.useCache are removed. The replacement is top-level cacheComponents: true, but that's a new model, not a rename. Don't switch it on just to finish the upgrade.

7. Parallel routes need default.js

Every @slot folder now needs an explicit default.js, or the build fails. To keep the old behavior:

export default function Default() {
  return null;
}

8. next/image defaults

None of these throw at build time. You find them when images look wrong or 400 in production.

• images.qualities now defaults to [75]. A quality={90} prop gets coerced to 75, and direct /_next/image requests with other q values return 400. List the qualities you use.
• Local images with query strings (/photo.png?v=1) need images.localPatterns with a search value.
• minimumCacheTTL went from 60 seconds to 4 hours. Set it back if your images change often.
• 16 was dropped from the default imageSizes.
• Images from local IPs are blocked unless you set images.dangerouslyAllowLocalIP (private networks only).
• At most 3 redirects are followed by default (images.maximumRedirects).
• images.domains and next/legacy/image are deprecated. Use remotePatterns and next/image. Remote host errors: next/image hostname is not configured.

9. Removed config and APIs

• serverRuntimeConfig and publicRuntimeConfig: read process.env in server code, and use NEXT_PUBLIC_ for values the browser needs. Call await connection() first if a value must be read at request time instead of build time.
• AMP: next/amp, useAmp and the amp config are gone.
• devIndicators: appIsrStatus, buildActivity and buildActivityPosition are removed.
• unstable_rootParams: use next/root-params.

10. Small behavior changes worth knowing

• next dev writes to .next/dev, so dev and build can run at the same time. A lockfile stops two next dev processes on one project.
• process.argv.includes("dev") inside next.config is now false during next dev. Check NODE_ENV instead.
• Next.js no longer overrides scroll-behavior: smooth during navigation. Add data-scroll-behavior="smooth" to <html> if you want the old behavior.
• next build no longer prints size and First Load JS. Use Lighthouse or real Core Web Vitals instead.
• React Compiler support is stable (reactCompiler: true) but off by default, and it slows builds. Leave it off until the upgrade is done.

Done? Check these before you ship

1. npm run build passes on the Node version your host actually uses.
2. Every dynamic route renders with real data. Click into a [slug] page, because the async params bug doesn't fail the build.
3. Auth still protects what it should after the proxy.ts rename. Open a protected page in a private window.
4. Images load in production at the quality you expect.
5. CI runs eslint itself, since next build no longer does.
6. Your AGENTS.md or Cursor rules say Next.js 16, so the agent doesn't undo all of this next week.

Still stuck on an error? Paste it into VibeBoot Doctor, which is free and runs in your browser, or browse the 70 fix pages for Next.js, Auth.js, Prisma and Stripe errors.