Skip to content

docs: tell quickstart readers how to get past the npm edgesOut crash - #3787

Merged
armando-navarro merged 3 commits into
angular:mainfrom
armando-navarro:b33-quickstart-npm-crash
Oct 5, 2026
Merged

armando-navarro merged 3 commits into
angular:mainfrom
armando-navarro:b33-quickstart-npm-crash

Conversation

@armando-navarro

Copy link
Copy Markdown
Collaborator

Fixes #3785

Adds one line under step 1 of docs/install-and-setup.md for readers whose npm create @angular@21 stops with npm error Cannot read properties of null (reading 'edgesOut').

Verification

On 2026-10-02, with Node.js 22.23.2:

  • npm create @angular@21 <project-name> on npm 10.9.8 fails with that error and leaves the project folder behind.
  • With npm 11.21.0 the same command installs.
  • Running it again into the leftover folder fails with A merge conflicted on path "/<project-name>/package.json"., which is why the line says to delete the folder first.
  • A new Angular 21 project fails to install on npm 10.8.2, 10.9.8, 10.9.9, 11.3.0 and 11.5.2, and installs on 11.6.0, 11.19.0, 11.21.0 and 12.2.0.
  • The line says npm@11 and not npm@latest because npm 12 requires Node.js 22.22.2 or later, and Angular 21 also supports Node.js 20.

`npm create @angular@21` fails with "Cannot read properties of null
(reading 'edgesOut')" on npm older than 11.6, which is what the
newest Node.js 20 and 22 releases come with. It is an npm bug
(npm/cli#9787), but a reader hits it at step 1.

The line says to delete the project folder because the failed run
leaves one behind, and running the command again into it fails with
a merge conflict on package.json.

Fixes angular#3785
@armando-navarro armando-navarro added bump: patch Size of the change: a fix or docs change that reaches users comp: docs Documentation. type: chore Maintenance with no user-facing behavior change. labels Oct 2, 2026

@tyler-reitz tyler-reitz left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approving.

One to watch: npm/cli#9787 is still open and labeled "Cannot Reproduce", so the 11.6 boundary rests on your bisect rather than on a landed fix. It could move again in a later npm.

Not blocking, but worth considering: Node 20.20.2 ships npm 10.8.2 and Node 22.23.3 ships npm 10.9.9, both in your failing set. So every reader on a current Node 20 or 22 hits this at step 1, not an unlucky subset. That may justify making npm install -g npm@11 an unconditional instruction in step 1 rather than a recovery line people only read after it breaks.

Every Node.js 20 and 22 release bundles npm 10, so the recovery note
under step 1 reached those readers only after the command had failed
once. Asking for npm 11.6 up front avoids the failure. The fix is
npm/cli#8448, shipped in arborist 9.1.4 with npm 11.6.0, and npm 10
stays on arborist 8.
@armando-navarro

Copy link
Copy Markdown
Collaborator Author

On the boundary, it turns out to be a landed fix: npm/cli#8448 closed npm/cli#8261, the same edgesOut error, and shipped in @npmcli/arborist 9.1.4, which npm 11.6.0 is the first to bundle. npm 10 is still on arborist 8, which is why 10.9.9 fails. npm/cli#9787 is the open report of it against npm 10.

I took your suggestion about making it unconditional. I moved it to "Before you begin" as a requirement for npm 11.6 or later, in the follow-up commit.

@armando-navarro
armando-navarro merged commit d3f8531 into angular:main Oct 5, 2026
24 checks passed
@armando-navarro armando-navarro added this to the 21.0.0-rc.2 milestone Oct 5, 2026
@armando-navarro
armando-navarro deleted the b33-quickstart-npm-crash branch October 5, 2026 03:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bump: patch Size of the change: a fix or docs change that reaches users comp: docs Documentation. type: chore Maintenance with no user-facing behavior change.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

The quickstart's first command fails on npm older than 11.6 (reading 'edgesOut')

2 participants