npm install crashes with 'Cannot read properties of null (reading package)' on nested file: dependencies (Windows)

[BobFrankston]

Note: I'm using AI assistance to clearly explain this bug, but this is my personal report based on a real crash I hit.

Description

npm install crashes with Cannot read properties of null (reading 'package') when a project has file: dependencies that themselves contain file: dependencies. Only affects Windows — the same project installs fine under WSL.

• npm: 11.7.0
• node: v25.3.0
• OS: Windows 11 Pro 10.0.22631

Stack trace

TypeError: Cannot read properties of null (reading 'package')
    at set root (node_modules/@npmcli/arborist/lib/node.js:799:35)
    at set parent (node_modules/@npmcli/arborist/lib/node.js:1322:15)
    at new Node (node_modules/@npmcli/arborist/lib/node.js:245:17)
    at new Link (node_modules/@npmcli/arborist/lib/link.js:17:5)
    at #newLink (node_modules/@npmcli/arborist/lib/arborist/load-actual.js:310:18)
    at #loadFSNode (node_modules/@npmcli/arborist/lib/arborist/load-actual.js:288:35)
    at async Promise.all (index 3)
    at async #loadFSTree (node_modules/@npmcli/arborist/lib/arborist/load-actual.js:327:7)
    at async #newLink (node_modules/@npmcli/arborist/lib/arborist/load-actual.js:317:7)
    at async #loadFSNode (node_modules/@npmcli/arborist/lib/arborist/load-actual.js:288:16)

Reproduction

Project A (package.json):

{
  "dependencies": {
    "pkgB": "file:../../../path/to/pkgB"
  }
}

Package B has its own file: dependencies:

{
  "dependencies": {
    "pkgC": "file:../../../../path/to/pkgC",
    "pkgD": "file:../../../../path/to/pkgD",
    "pkgE": "file:../../../../../path/to/pkgE"
  }
}

Run npm install in Project A on Windows. The crash occurs during the idealTree/placeDep phase. The verbose log shows:

silly placeDep ROOT addlifx@1.0.0 OK for: haupdate@1.0.0 want: file:../../../LifX/Apps/addlifx
verbose stack TypeError: Cannot read properties of null (reading 'package')

Analysis

#newLink in load-actual.js:310 creates a Link node whose target is null. The Link constructor calls new Node() which calls set parent → set root, which dereferences target.package — but target is null.

This appears to happen because #loadFSTree uses Promise.all to process child nodes concurrently. On Windows, a Link target for a nested file: dependency may not be loaded yet when its parent Link is being constructed.

Workaround

Running npm install under WSL (Linux) on the same project tree succeeds. I wrote a wrapper script that falls back to WSL and converts the resulting symlinks to junctions for Windows compatibility.