vercel / vercel/next.js

Turbopack panics when a Git worktree symlinks node_modules to the primary checkout

Open
#98,111 1 comment 0 reactions 0 assignees View on GitHub

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.

  1. Clone the reproduction repository.
  2. Install dependencies with pnpm install.
  3. 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.