Your npm install is failing because the npm CLI is trying to use corrupted or outdated package data from its local cache.
Here’s how to fix it, covering all the common culprits:
Corrupted Cache Files
Sometimes, individual package files within the npm cache get corrupted due to interrupted downloads, disk errors, or other unforeseen issues. This is the most frequent cause of cache-related npm install failures.
Diagnosis: Look for specific error messages during npm install that mention failing to read a particular file or a checksum mismatch for a downloaded package.
Fix: Clear the entire npm cache. This forces npm to re-download all packages from scratch.
npm cache clean --force
This command removes all files from ~/.npm (or your configured cache directory), ensuring a clean slate. The next npm install will fetch fresh copies of all dependencies.
Stale package-lock.json or npm-shrinkwrap.json
These lock files are crucial for reproducible builds, but if they point to packages that are no longer valid in the cache (due to a cache clear or other reasons), you can run into issues.
Diagnosis: Errors might manifest as 404 Not Found for specific package versions, even though you know they exist in the registry.
Fix: Delete your lock file and reinstall.
rm package-lock.json
npm install
Deleting package-lock.json tells npm to resolve dependencies based on package.json and then generate a new lock file. npm install will then fetch the required packages, populating the cache with fresh, valid data.
Outdated npm CLI Version
Older versions of npm might have bugs related to cache handling or may not be compatible with newer registry features, leading to cache corruption or misinterpretation.
Diagnosis: Check your npm version with npm -v. If it’s significantly old (e.g., below v6), it’s a potential issue.
Fix: Update npm to the latest version.
npm install -g npm@latest
This command updates the global npm CLI package. A newer version often includes fixes for cache management and improved resilience against corrupt cache entries.
Insufficient Disk Space
While less common for cache errors specifically, a full disk can prevent npm from writing new cache entries or even reading existing ones correctly, leading to seemingly random failures.
Diagnosis: Check your available disk space using df -h on Linux/macOS or checking drive properties on Windows.
Fix: Free up disk space by deleting unnecessary files or clearing other caches (like browser caches, system logs, etc.).
Ensuring sufficient free space allows npm to operate without I/O errors when writing to or reading from the cache directory.
Network Issues During Cache Population
Intermittent network problems during npm install can lead to incomplete or corrupted downloads being stored in the cache, even if the final npm install command appears to succeed initially. Subsequent installs might then try to use these bad cache entries.
Diagnosis: Look for specific download errors during npm install that were previously ignored or seemed transient. Also, consider if the failure occurs consistently on a specific machine or network.
Fix: Clear the cache and try installing again from a stable network connection.
npm cache clean --force
npm install
A stable network ensures that all package files are downloaded completely and without corruption, preventing bad data from entering the cache in the first place.
Permissions Issues with the Cache Directory
If the npm cache directory (~/.npm by default) has incorrect file permissions, npm might not be able to read or write to it properly, causing errors.
Diagnosis: Check the ownership and permissions of your npm cache directory.
ls -ld ~/.npm
You should see read/write permissions for your user.
Fix: Ensure your user owns the cache directory and has appropriate permissions.
sudo chown -R $(whoami) ~/.npm
chmod -R u+rw ~/.npm
This resets ownership to your current user and grants read/write permissions for the owner, allowing npm to freely manage its cache files.
After resolving these, you might encounter EPROTO errors if your Node.js version is too old and doesn’t support the TLS versions required by the npm registry.