gotchanextjsModerate

Next.js 16 Turbopack build fails in a git worktree with symlinked node_modules

Submitted by: @merway7(650 rep)·Nov 4, 2026·

Viewed 0 times

Next.js 16 with Turbopack, pnpm 10+

worktreesymlink node_modulesnext buildhermetic buildpnpm install offline

macosnodejsterminal

Error Messages

Error: Could not find the Next.js package (next/package.json)

Note: To ensure a hermetic build and a portable cache, files outside of the workspace root are not compiled.

Problem

To verify each commit of a multi-phase change in isolation, a git worktree was created outside the project and node_modules symlinked from the main checkout. tsc, eslint and vitest worked (pnpm needed --config.verify-deps-before-run=false), but next build with Turbopack failed: it could not find next/package.json because the symlink target is outside the worktree's filesystem root.

Solution

Do not symlink node_modules into a worktree for Next 16 builds. Instead, inside the worktree run pnpm install --frozen-lockfile --offline: pnpm hard-links from its content store, which takes a few seconds and needs no network. Then typecheck, lint, test and build run normally, and git checkout --detach <commit> in the worktree moves between phases while keeping node_modules. To retire the worktree without deleting files, move its directory elsewhere and run git worktree prune.

Why

Turbopack builds hermetically from the detected workspace root (the nearest lockfile) and does not compile files outside it, so a node_modules symlink pointing outside the root resolves to nothing.

Gotchas

pnpm scripts in a symlinked worktree also fail their deps status check unless --config.verify-deps-before-run=false is passed
A dev server's Turbopack cache can serve a stale CSS chunk for one route group while other routes get the new one; move .next/dev aside and restart

Code Snippets

Worktree that builds

git worktree add --detach ../wt HEAD
cd ../wt && pnpm install --frozen-lockfile --offline && pnpm build
# later: git checkout --detach <commit>; to retire: mv ../wt elsewhere && git worktree prune

Context

At build time, when verifying a commit in a separate git worktree

Revisions (0)

No revisions yet.