Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

ng update stops on peer dependency errors when moving to a much newer Angular

ErrorIncompatible peer dependencies found.

Short answer

Angular supports updates one major version at a time, so a jump such as 8 to 13 in one go leaves packages whose peer ranges do not match. Update each major in turn with ng update, update third-party packages that block a step, and use --force only for a conflict you have judged harmless.

  • Applies to Angular CLI 21, Node.js 24, npm 11
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Print the Angular packages currently installed. Every @angular/* package must be on the same major before you start the next step.

    npm ls @angular/core @angular/cli @angular/material
  2. 2Match what you see, then jump to its fix

    1. 1The conflict names packages that need a range several majors away from the one you targetYou skipped majorsFix
    2. 2Incompatible peer dependencies found, naming a package that is not @angular/core or @angular/cliA third-party package has an older peer rangeFix
    3. 3Error: Repository is not clean. Please commit or stash any changes before updatingng update refuses because the repository has uncommitted changesFix

What does the error look like?

  • Incompatible peer dependencies found.
  • Peer dependency warnings when installing dependencies means that those dependencies might not work correctly together.
  • Error: Repository is not clean. Please commit or stash any changes before updating

Cause 1 of 3

You skipped majors

1Check

Compare the major in package.json with the one you are trying to install. The Angular release policy tells you to cross several majors one at a time.

npm ls @angular/core --depth=0

2Fix

Commit your work, then update core and CLI to the next major only, finish that step (build and tests), and repeat. The version you pass is the next major, not the final one.

git status
npx ng update @angular/core@<next-major> @angular/cli@<next-major>

3Verify

After each step, the build passes and npm ls shows one major for every @angular package.

npm ls @angular/core --depth=0
npx ng build

Confirmed by angular.dev

Did this fix it?

Cause 2 of 3

A third-party package has an older peer range

1Check

Libraries declare which Angular versions they accept in peerDependencies. A release built for the old major rejects the new core.

npm ls <package-name>

2Fix

Update that package in the same ng update call, so its own migration runs, or move to a release that lists your target major. Only then add --force, which ignores peer version mismatches and does not fix an API that really changed.

npx ng update @angular/core@<next-major> @angular/cli@<next-major> <package-name>
# last resort, one package, after reading its changelog:
npx ng update <package-name> --force

3Verify

The update completes and the build shows no template or type errors from that library.

npx ng build

Confirmed by github.com

Did this fix it?

Cause 3 of 3

ng update refuses because the repository has uncommitted changes

1Check

Untracked files count too, not only edits; node_modules and build output should be in .gitignore.

git status --short

2Fix

Commit or stash first. Pass --create-commits so each update and migration becomes its own commit; use --allow-dirty only when you accept losing that clean diff.

git add -A && git commit -m "before angular update"
npx ng update @angular/core@<next-major> @angular/cli@<next-major> --create-commits

3Verify

git log shows one commit per migration, ready to review or revert.

git log --oneline -n 10

Confirmed by angular.dev

Did this fix it?

How do I stop it coming back?

  • Update every Angular major as it ships, or at least within a supported window, instead of letting years pile up.
  • Run ng update from a clean branch and keep --create-commits on, so a bad step can be reverted alone.
  • Check the Node.js and TypeScript ranges on the Angular versions page before each step.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Back end

ng serve says it cannot determine the project or target

Cannot determine project for command.

The Angular CLI looked through angular.json for a project that defines the target you asked for (serve, build, test) and found none, or found several and could not pick one.

3 causes, each with a fix

Back end

ng serve cannot find the dev-server builder package

Could not find the implementation for builder @angular/build:dev-server

The builder named in angular.json (for example @angular-devkit/build-angular:dev-server) is looked up as an npm package starting from the workspace root.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.