Turbopack panics when a Git worktree symlinks node_modules to the primary checkout
Nobody has claimed this yet.
- Dominant language
- JavaScript
- Stars
- 142k
- Forks
- 32.4k
- Avg merge
- 2d 14h
- Merged PRs (30d)
- 351
Description
Link to the code that reproduces this issue
https://github.com/Innei/next-turbopack-external-node-modules-worktree-repro
To Reproduce
The reproduction is based on the official reproduction-template and uses the
latest available canary release.
- Clone the reproduction repository.
- Install dependencies with
pnpm install. - Run
./reproduce.sh.
The script creates a sibling Git worktree, symlinks the worktree's node_modules
to the dependency installation in the primary checkout, and starts next dev from
the worktree.
The same application starts normally when next dev is run directly from the
primary checkout.
Current vs. Expected behavior
Current behavior
Turbopack prints its ready message and then exits with an internal panic before the
application can be served:
Symlink node_modules could not be resolved: the symlink target leaves the filesystem root or its parent directory could not be resolved
Expected behavior
next dev should resolve the accessible external node_modules symlink and run the
application from the Git worktree. If external dependency roots cannot be supported
by default, Next.js should provide an explicit opt-in configuration for them and
report an actionable configuration error instead of an internal Turbopack panic.
Provide environment information
Operating System:
Platform: darwin
Arch: arm64
Version: Darwin Kernel Version 25.4.0
Available memory (MB): 131072
Available CPU cores: 16
Binaries:
Node: 24.18.0
npm: 11.7.0
Yarn: 1.22.22
pnpm: 11.24.0
Relevant Packages:
next: 16.4.0-canary.12
eslint-config-next: N/A
react: 19.2.8
react-dom: 19.2.8
typescript: 5.9.3
Next.js Config:
output: N/A
Which area(s) are affected?
Turbopack, Module Resolution
Which stage(s) are affected?
next dev (local)
Additional context
AI-assisted development increasingly runs several independent coding sessions in
parallel, with each session isolated in its own Git worktree. Reinstalling a large
dependency graph for every short-lived worktree adds significant setup time and
filesystem overhead, so sharing the primary checkout's existing node_modules
through a symlink is a practical worktree strategy.
This makes external dependency symlinks especially relevant for multi-session agent
workflows, where worktrees are created and discarded frequently. Supporting this
layout, or providing a narrowly scoped allowlist for external dependency roots,
would make Turbopack usable in those workflows without requiring a separate full
installation for every session.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the linked reproduction repository and run reproduce.sh after pnpm install to confirm the Turbopack panic. Trace Turbopack's module-resolution handling for symlinked node_modules outside the worktree. Done means next dev serves the worktree without an internal panic, or reports an actionable error if the layout remains unsupported.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- git, javascript, nextjs, node.js
- Domain
- build-system, tooling
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 50/100