How to Fix: blitz dev –turbo (next wrapper) broken since Next 15.0.0-rc.1

Blitz’s blitz dev --turbo breaks with Next 15.0.0-rc.1 because the wrapper is coupled to internal Next.js dev-server behavior that changed in the release candidate. If your app suddenly stops booting in development after upgrading, the fix is usually not in your app code at all—it is in how Blitz delegates to Next’s new Turbopack-powered dev command.

The issue tracked in the original GitHub report appears when Blitz’s Next wrapper forwards the development command in a way that no longer matches Next 15 RC internals. In practice, blitz dev --turbo may fail to start, ignore flags, or crash during startup depending on the exact Blitz and Next versions installed.

Understanding the Root Cause

Blitz builds on top of Next.js and exposes commands like blitz dev as a higher-level developer experience. Historically, that wrapper could rely on a fairly stable invocation path for Next’s dev server. With Next 15.0.0-rc.1, the development startup path changed enough that Blitz’s wrapper behavior became incompatible.

Technically, the problem comes from one or more of these changes:

• Next 15 RC adjusted its CLI argument handling for dev mode and Turbopack-related flags.
• Blitz’s wrapper likely depends on internal Next APIs or command semantics rather than only a public stable interface.
• The meaning or forwarding of the --turbo flag changed as Next moved further toward its newer dev tooling model.
• Release candidates often include breaking internal refactors that wrappers and meta-framework tooling have not yet adapted to.

That means your application code is usually not the root cause. The failure happens at the boundary between Blitz CLI and Next’s dev server startup. If Blitz invokes Next using assumptions from pre-15 behavior, the wrapper can break even before your routes, queries, or RPC endpoints are loaded.

In short: Blitz is acting as a thin compatibility layer, and Next 15 RC changed the shape of what that layer needs to call.

Step-by-Step Solution

The most reliable fix is to use a version combination where Blitz and Next agree on dev-server behavior. Until Blitz officially supports Next 15 RC for the wrapper path, you should either downgrade Next or avoid the broken wrapper path.

Option 1: Pin Next to a compatible stable version

If you do not specifically need Next 15 RC features, this is the safest solution.

npm uninstall next
npm install next@14 react@18 react-dom@18

Or with pnpm:

pnpm remove next
pnpm add next@14 react@18 react-dom@18

Then remove lockfile drift and reinstall cleanly:

rm -rf node_modules .next
rm -f package-lock.json pnpm-lock.yaml yarn.lock
npm install

Start the app again:

blitz dev --turbo

If you want maximum compatibility, you can also temporarily skip Turbopack:

blitz dev

Option 2: Run Next directly as a temporary workaround

If the bug is specifically in the Blitz wrapper, invoking Next directly can help confirm that your project itself is otherwise healthy.

npx next dev --turbo

Or add a package script:

{
  "scripts": {
    "dev:next": "next dev --turbo"
  }
}

npm run dev:next

If direct Next startup works while blitz dev --turbo fails, you have validated that the issue is in the wrapper layer rather than in application code.

Option 3: Patch your dependencies to a Blitz-compatible release

Check whether a newer Blitz release, canary, or patch has landed since the issue was opened. If support was added, upgrade Blitz first and keep your Next version aligned with that support window.

npm install blitz@latest @blitzjs/next@latest

After upgrading, reinstall and retry:

rm -rf node_modules .next
npm install
blitz dev --turbo

Option 4: Lock versions explicitly in package.json

To prevent accidental upgrades back to the incompatible RC path, pin your framework versions.

{
  "dependencies": {
    "next": "14.2.30",
    "react": "18.3.1",
    "react-dom": "18.3.1"
  }
}

If you are in a workspace or monorepo, also verify that no nested package pulls in a conflicting Next version:

npm ls next

With pnpm:

pnpm why next

Recommended practical resolution

For most teams, the best immediate path is:

1. Downgrade from Next 15.0.0-rc.1 to a Blitz-supported stable Next version.
2. Clean reinstall dependencies.
3. Retry blitz dev first, then blitz dev --turbo.
4. Track the upstream issue at Blitz issue #4395 for an official wrapper fix.

Common Edge Cases

• Mismatched React versions: Next 15 RC may pull in React versions that differ from what your Blitz app previously used. Always verify react and react-dom match the expected framework pair.
• Lockfile residue: Even after editing package.json, an old lockfile can preserve the broken dependency tree. Remove the lockfile and reinstall if the downgrade seems ineffective.
• Monorepo hoisting issues: In Turbo, pnpm, or Yarn workspace setups, a root dependency can override the app’s local version of Next. Use dependency inspection commands to confirm only one intended version is active.
• Cached build artifacts: A stale .next directory can make debugging confusing. Delete it before retesting.
• Using RC builds in production-like dev environments: Release candidates are not guaranteed to preserve internal interfaces. Wrappers such as Blitz often lag RC changes until maintainers explicitly adapt and test them.
• Direct Next works, Blitz fails: This strongly indicates a wrapper incompatibility rather than a route, config, or compiler issue.
• Custom Next config: Experimental flags in next.config.js can amplify startup failures when combined with RC builds and Turbopack.

FAQ

1. Why does blitz dev sometimes work while blitz dev --turbo fails?

Because the failure is tied to the Turbopack-specific dev startup path. Standard dev mode may still use a code path that remains compatible, while the --turbo flow exercises newer Next 15 RC behavior that Blitz has not yet adapted to.

2. Can I keep Next 15.0.0-rc.1 and still use Blitz?

Possibly, but not reliably through blitz dev --turbo until Blitz officially supports that RC behavior. Your best temporary workaround is to run Next directly for testing or downgrade to a stable supported Next version for daily development.

3. Is this caused by my application routes, RPC layer, or database code?

Usually no. The bug happens early in the CLI-to-framework handoff. If the dev server does not initialize correctly, your app modules may never even load. That is why version alignment between Blitz and Next is the primary fix.

Bottom line: this bug is a framework integration regression, not an app-level coding mistake. Until Blitz ships a wrapper update for Next 15 RC, pin to a supported Next release or bypass the broken wrapper path by launching Next directly.