From 567bfbde67a96aeca9ce0f3f7a17ac9f7e942218 Mon Sep 17 00:00:00 2001 From: Brian Love Date: Sun, 30 Aug 2026 07:45:57 -0700 Subject: [PATCH] docs: worktree-only Turbopack panic when website .next caches exist MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit nx build cockpit dies with 'FileSystemPath(...).join(...) leaves the filesystem root' in a git worktree whenever apps/website/.next or dist/apps/website exists. The caches hold a node_modules symlink whose relative target routes through the MAIN checkout's root — valid on disk, but Turbopack's virtual filesystem refuses to traverse above its project root. Verified: pinning turbopack.root does NOT fix it; clearing the caches does (build goes 1 -> 0). CI is unaffected (fresh, un-nested checkouts). Co-Authored-By: Claude Opus 5 --- CONTRIBUTING.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5ccdbe38e..ad79960ab 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -52,6 +52,22 @@ Do not run `npm install` in a worktree on macOS either: it rewrites `package-lock.json` and drops the Linux `@next/swc-*` bindings, which breaks CI. `npm ci` is the safe command. +One more worktree-only trap, after install: `nx build cockpit` can die with a +Turbopack panic — `FileSystemPath(...).join(...) leaves the filesystem root` — +whenever a website `.next` cache exists anywhere in the workspace +(`apps/website/.next` from `next dev`/e2e, or `dist/apps/website` from a build). +Those caches contain a `node_modules` symlink whose relative target resolves +through the *main* checkout's root; the path is valid on disk, but Turbopack's +virtual filesystem refuses to traverse above its project root and panics. +Pinning `turbopack.root` does not help. Clear the caches instead: + +```bash +rm -rf apps/website/.next dist/apps/website && npx nx build cockpit +``` + +CI never hits this — its jobs build from fresh checkouts that are not nested +inside another checkout. + ## Testing New functionality and bug fixes must include automated tests. Run a project's