Maaz Zindani

Loading the index…

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

next build refuses to start because Partial Prerendering is switched on in next.config

Your error

[Error: The experimental feature "experimental.ppr" can only be enabled when using the latest canary version of Next.js.]1 more line it can show

Fix it fast

Most common cause, 1 of 2

PPR is enabled on a stable 15.x release

For a production app on stable, delete the flag together with every experimental_ppr export in your routes.

Fix
// next.config.js on stable 15.x
module.exports = {
  experimental: {
    // ppr: true,  <- removed
  },
}

# only if you really want the experiment
npm install next@canary
Did this fix it?
Full steps for this cause: check, fix, verify

Short answer

On a stable Next.js 15 release, Partial Prerendering was a canary-only experiment, so a next.config with experimental.ppr makes the build stop at once. Either remove the flag, or install next@canary on purpose. On Next.js 16 the flag and the experimental_ppr route export are gone; turn on cacheComponents: true instead and delete the old options.

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

Which cause do you have?

Check which Next.js you actually have installed and whether the config or any route still asks for PPR.

Run this first
npx next --version
grep -rnE "ppr|experimental_ppr" next.config.* app src 2>/dev/null

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

  1. 1PPR is enabled on a stable 15.x releasenext --version prints a plain 15.x number and next.config contains experimental: { ppr: true } or ppr: 'incremental'
  2. 2The project moved to Next.js 16 with the old PPR settingsnext.config still has experimental.ppr, or pages export const experimental_ppr = true, after an upgrade to 16

What does the error look like?

  • [Error: The experimental feature "experimental.ppr" can only be enabled when using the latest canary version of Next.js.]
  • > Build error occurred

Cause 1 of 2

PPR is enabled on a stable 15.x release

You seenext --version prints a plain 15.x number and next.config contains experimental: { ppr: true } or ppr: 'incremental'

Check

The Next.js 15 docs mark the ppr option as available in the canary channel only. Stable releases check for it at startup and stop the build before compiling anything.

Check
node -e "console.log(require('next/package.json').version)"

Fix

For a production app on stable, delete the flag together with every experimental_ppr export in your routes. Use canary only when you accept a moving target.

Fix
// next.config.js on stable 15.x
module.exports = {
  experimental: {
    // ppr: true,  <- removed
  },
}

# only if you really want the experiment
npm install next@canary

Verify

The build gets past the config step and prints the route table.

Verify
npx next build

Confirmed by nextjs.org

Did this fix it?

Cause 2 of 2

The project moved to Next.js 16 with the old PPR settings

You seenext.config still has experimental.ppr, or pages export const experimental_ppr = true, after an upgrade to 16

Check

The version 16 upgrade guide removes the experimental PPR flag, its config options and the experimental_ppr route segment export. PPR is now reached through Cache Components.

Check
grep -rn "experimental_ppr" app src

Fix

Run the upgrade codemod, remove leftovers by hand, and switch on cacheComponents at the top level of the config. With it on, dynamic data is uncached by default and you mark cacheable parts with the use cache directive.

Fix
npx @next/codemod@canary upgrade latest

// next.config.ts
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
  cacheComponents: true,
}
export default nextConfig

Verify

The build finishes, and routes with a static shell plus streamed parts show up as partially prerendered in the route table.

Verify
npx next build

Confirmed by nextjs.org

Did this fix it?

How do I stop it coming back?

  • Pin the exact Next.js version in package.json when you rely on an experimental flag.
  • Read the upgrade guide's removed features list before moving to a new major version.
  • Keep experiments on a branch until the feature leaves canary.

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.