Understanding the ERESOLVE Error
When you attempt to install @angular/material using npm, you may encounter an error with the code ERESOLVE. This is not a bug in Angular or Material itself, but rather a strict dependency resolution mechanism introduced in newer versions of npm (version 7 and above). The package manager refuses to install the requested package because it detects a conflict between the required version of a peer dependency and the version currently installed in your node_modules directory.
This often happens when upgrading an existing Angular application. For instance, if your project uses Angular 14 but you try to install a version of Material designed for Angular 15, npm will block the installation to prevent runtime crashes. Similarly, mixing different major versions of third-party libraries can trigger this safeguard. Understanding that this is a protective measure helps in diagnosing the root cause rather than treating it as a random failure.
Verifying Version Compatibility
The most common cause of installation failure is a mismatch between the Angular core version and the Material library version. Each major release of Angular requires a corresponding major release of Material. Before attempting any fixes, you must ensure that the versions are aligned. You can check your current Angular version by running ng version in your terminal. Look at the "Angular CLI" and "@angular/core" sections.
If you are using Angular 13, you should install @angular/material@13. If you are on Angular 14, use @angular/material@14, and so on. Installing a generic @angular/material without specifying a version might pull the latest available version, which could be incompatible with your older Angular setup. To fix this, explicitly specify the version tag during installation:
npm install @angular/material@14 @angular/cdk@14Replace 14 with your specific Angular major version number. This ensures that the peer dependencies declared by the Material package match what is already present in your project. Always install @angular/cdk alongside Material, as they are tightly coupled and share version constraints.
Clearing the NPM Cache
Sometimes, the issue stems from corrupted cache files or stale metadata that confuse the resolver. A simple yet effective troubleshooting step is to clear the npm cache. This forces npm to re-fetch package information from the registry rather than relying on potentially outdated local data. Run the following command to clean the cache:
npm cache clean --forceAfter clearing the cache, delete your node_modules folder and the package-lock.json file. This removes all previously resolved dependencies. Then, run npm install again. This process rebuilds the dependency tree from scratch. In many cases, this resolves transient issues where the lock file contains conflicting resolutions that no longer make sense after a partial update.
Using the Force Flag
If verifying versions and clearing the cache does not resolve the issue, you may need to override the strict peer dependency checks. This is done using the --legacy-peer-deps flag or the --force flag. The --legacy-peer-deps option tells npm to ignore peer dependency conflicts, mimicking the behavior of npm v6. This is often the safest approach for upgrading projects where some dependencies might not have been updated to support the new peer requirements.
npm install @angular/material --legacy-peer-depsAlternatively, the --force flag will proceed with the installation even if it results in a broken dependency graph. Use this with caution, as it may lead to runtime errors if the underlying libraries are truly incompatible. However, for minor version mismatches or when you are certain the packages work together, this flag allows the installation to complete. It is recommended to start with --legacy-peer-deps before resorting to --force.
Updating Angular CLI and Core Packages
In some scenarios, the resolution engine itself needs updating. Ensure that your global Angular CLI and local Angular core packages are up to date. An outdated CLI might use an older resolver algorithm that behaves unexpectedly. Update your global CLI using:
npm install -g @angular/cliThen, update your local project dependencies:
npm install @angular/cli@latest @angular/core@latestThis aligns your tooling with the latest standards. If you are migrating between major versions, consider using the Angular DevKit schematics to automate the upgrade process, which handles dependency updates more intelligently than manual npm installs. For related routing issues that may arise during such upgrades, see our guide on Troubleshooting Guest Guard Initiation Error on Home Route in Angular.
Frequently Asked Questions
Why does npm complain about peer dependencies?
Npm enforces peer dependencies to ensure that installed packages are compatible with each other. If a package requires a specific version of another library that you do not have, npm blocks installation to prevent runtime errors. This is a safety feature to maintain project stability.
Can I ignore peer dependency warnings?
Yes, you can use the --legacy-peer-deps flag to bypass these checks. This allows installation to proceed even if versions do not strictly match. However, be aware that ignoring these warnings might lead to unexpected bugs if the libraries are fundamentally incompatible.
Do I need to reinstall node_modules every time?
Not necessarily, but deleting node_modules and package-lock.json is a good practice when facing persistent resolution errors. It ensures a clean slate and prevents cached conflicts from interfering with new installations. Always back up your code before deleting these folders.
What is the difference between --force and --legacy-peer-deps?
--legacy-peer-deps ignores peer dependency conflicts while still respecting other dependency rules. --force overrides almost all checks, including non-peer conflicts, and can lead to a broken dependency tree. Prefer --legacy-peer-deps for safer upgrades.
How do I check my current Angular version?
Run the command ng version in your terminal. The output will display the versions of Angular CLI, Angular Core, and other relevant packages. Compare this with the version of Material you intend to install to ensure compatibility.