How to Fix: next build with 15.0.2-canary.6 fails while pnpm build with the same passes

The failure is caused by version skew: the globally installed Next.js CLI is not the same build as the project-local canary dependency, so next build resolves different code paths depending on whether you run the global binary or the package-manager script.

Understanding the Root Cause

This issue appears when a project is created with Next 15.0.2-canary.6, but the command you run from the shell is a different globally installed next executable, typically from pnpm i -g next@latest. On the surface, both commands look similar:

next build
pnpm build

But they do not necessarily execute the same binary.

When you run pnpm build, pnpm prefers the project-local dependency tree. That means the build uses the exact version declared in the app, including the matching canary internals expected by that repository.

When you run next build after globally installing Next, your shell may invoke the global CLI instead. If that global package is newer, older, or simply built from a different release channel than the app dependency, the CLI and the project runtime can disagree about internal APIs, file layout, or build behavior.

This is especially sensitive with canary releases, because canary versions often include internal changes that are only guaranteed to work when the CLI and local package version are aligned.

In short, the bug is usually not that pnpm build and next build are fundamentally different features. The real problem is that they may execute different Next.js versions.

Typical symptoms include:

• Build passing through pnpm build but failing through next build
• Unexpected module resolution or internal build errors
• Inconsistent behavior after installing next globally
• Problems that only appear on canary and not stable releases

Step-by-Step Solution

The safest fix is to stop using the global Next.js CLI for project builds and always execute the local version installed in the repository.

1. Check which Next.js versions are involved

node -v
pnpm -v
pnpm list next
next --version

If next --version does not match the version inside the project, you have confirmed the mismatch.

2. Use the project-local build command

Run the build through the package manager:

pnpm build

Or explicitly run the local binary:

pnpm exec next build

This ensures the command resolves to the repository’s installed Next.js version, not the global one.

3. Remove the global Next.js install

If you do not specifically need a global installation, uninstall it to avoid accidental conflicts:

pnpm remove -g next

After that, verify the shell no longer resolves the global binary:

which next

On Windows, use:

where next

4. Reinstall dependencies cleanly

If the project has already mixed binaries or caches, do a clean install:

rm -rf node_modules .next pnpm-lock.yaml
pnpm install
pnpm build

On Windows PowerShell:

Remove-Item -Recurse -Force node_modules, .next
Remove-Item -Force pnpm-lock.yaml
pnpm install
pnpm build

5. Pin the exact Next.js version

In package.json, keep the dependency pinned to the exact canary version used by the app instead of a loose range.

{
  "dependencies": {
    "next": "15.0.2-canary.6",
    "react": "...",
    "react-dom": "..."
  }
}

This reduces the chance of unintentional upgrades during install.

6. Prefer script-based workflows in teams and CI

Define and use scripts so every developer and every CI runner uses the same entrypoint:

{
  "scripts": {
    "build": "next build",
    "dev": "next dev",
    "start": "next start"
  }
}

Then always run:

pnpm build

This is the most reliable path because it keeps tool resolution local and deterministic.

Recommended working approach

# do not install next globally for this project
pnpm install
pnpm exec next --version
pnpm exec next build

If you want to inspect the reproduction repository, use the test app on GitHub.

Common Edge Cases

1. Shell command caching

Some terminals cache command locations. Even after uninstalling global next, the shell may still point to the old executable until you restart the terminal session.

Fix:

hash -r

Or simply close and reopen the terminal.

2. Multiple package managers in the same repo

If a project mixes npm, pnpm, or yarn lockfiles, dependency resolution can drift.

Fix: keep only one lockfile, preferably the one for the package manager you actually use.

3. Different Node.js versions

A local machine may be using one Node version while CI uses another. Canary builds can expose compatibility differences faster than stable releases.

Fix: standardize with .nvmrc, .node-version, or your CI runtime config.

4. PATH ordering issues

If your global binary directory appears before local tool shims in PATH, calling next directly may hit the wrong executable.

Fix: use pnpm exec next build or script commands instead of relying on raw PATH lookup.

5. Hidden cache artifacts

Old .next output or stale dependency caches can make it look like the version mismatch is still present.

Fix: remove .next, reinstall dependencies, and retry the build from a clean state.

6. Upgrading only one side of the toolchain

Upgrading the global CLI without upgrading the local dependency, or vice versa, can recreate the same problem later.

Fix: treat Next.js CLI execution and project dependency version as a matched set.

FAQ

Why does pnpm build pass while next build fails?

Because pnpm build usually uses the local project binary, while next build may use a global binary. If those versions differ, the behavior can diverge.

Is this specific to Next 15 canary builds?

It can happen on stable versions too, but canary releases are more likely to surface it because internal changes move faster and version mismatches are less forgiving.

Should I ever install Next.js globally?

For application development, it is generally better to avoid global installation and rely on the project-local dependency through pnpm exec or package scripts. That keeps builds reproducible across machines.

Bottom line: if a Next.js app builds with pnpm build but not with next build, assume a global-vs-local CLI mismatch first. Use the local binary, remove the global install, and keep the project pinned to one exact Next.js version.