How to Fix Common npm install Errors

Almost every npm install failure prints a line starting with npm ERR! and a short code: ERESOLVE, EACCES, ENOENT, and a handful of others. Those codes are the whole game: each one points at a distinct class of problem with a distinct fix, and once you can read them you stop guessing. This is a field guide to the ones you'll actually meet, in roughly the order they show up in modern projects.

Most install errors are one of a small number of things, and a few reflexes clear the majority of them before you need to understand the specific code:

• Read the whole error, not just the last line. npm prints the actual cause several lines up; the final line is often just a pointer to the log file.
• Check your Node and npm versions. A package that needs Node 20 will fail in confusing ways on Node 16.
• Delete node_modules and the lockfile, then reinstall. This alone fixes a surprising share of "it worked yesterday" failures.
• Clear the cache if you see integrity or checksum errors.

A peer dependency is a package's way of saying "I don't bundle React myself; I expect you to provide a compatible one." That range is declared by the library author, so ERESOLVE is frequently about a library's declared React (or other framework) version range being narrower than reality: the library works fine with React 18, but its author only ever declared peerDependencies: { "react": "^17.0.0" }. A typical error looks like this:

You have three ways out, in order of preference:

• Fix the actual version. The correct fix: upgrade some-legacy-lib to a version whose peer range includes React 18, or if none exists, decide whether you can move the conflicting package to a version everyone agrees on. This resolves the conflict rather than hiding it.
• Install with --legacy-peer-deps. This ignores peer conflicts and installs anyway (npm 6 behaviour). Appropriate when the peer range is merely too strict and you've confirmed the library actually works with your version. It's the mild override.
• Install with --force. This goes further and will happily install broken or duplicated trees. Risky: reserve it for genuine emergencies, and expect to clean up afterward.

EACCES means npm tried to write somewhere your user account doesn't own, almost always a global install path such as /usr/local/lib/node_modules. The tempting fix is sudo npm install -g, and it's the wrong one: it creates root-owned files and folders that generate more permission errors later, and it runs package install scripts as root, which is a genuine security risk.

The real fix is to stop needing elevated permissions at all. The cleanest route is a version manager like nvm, which installs Node and all global packages under your home directory, where you already have write access. Alternatively, point npm's global prefix at a folder you own.

ENOENT is Node's "error: no entity": a file or directory npm expected to exist simply isn't there. On install it usually means one of three things:

• You're in the wrong directory. There's no package.json where you ran the command. npm install looks for it in the current folder; if you're one level too high, you get ENOENT: no such file or directory, open '.../package.json'.
• The package.json is genuinely missing in a freshly cloned repo or a subfolder that isn't a package.
• A script or dependency references a file that doesn't exist, a postinstall hook pointing at a moved file, for instance.

The same class of missing-path problem at runtime is the Cannot find module error, which is worth reading alongside this if your install succeeds but node then can't load something.

ETARGET (often printed as notarget) means you asked for a specific version of a package that doesn't exist on the registry. Common triggers: a typo in the version string, pinning to a version that was never published, or a version range in package.json that no published release satisfies. The error names both the package and the version you requested, which makes it one of the easier codes to diagnose: check what's actually published.

Codes like ETIMEDOUT, ECONNREFUSED, ECONNRESET, and ENOTFOUND mean npm couldn't reach the registry to download packages. The cause is rarely npm itself. It's the network in between. The usual suspects are a flaky connection, a corporate proxy that npm doesn't know about, or a registry misconfiguration (a private registry URL that's down, or a stale .npmrc pointing somewhere it shouldn't).

npm caches every package tarball it downloads and verifies each one with an integrity hash. When a cached file is corrupted, or when package-lock.json disagrees with package.json, installs fail with integrity/checksum errors or with npm ci refusing to run because the lockfile is out of sync. The fix is a clean reset: clear the cache, delete the installed tree and the lockfile, and let npm rebuild both from scratch.

The most maddening install errors are the ones that only happen in continuous integration: green on your laptop, red on the build server. Almost always it's an environment difference: a different Node version, a different OS, a lockfile that's committed in one state but installed in another, or a cache that's fresh in CI and warm locally. The way to make these reproducible is to capture the exact environment where the failure happened (Node version, OS, and lockfile state) so you can recreate it rather than guess at it.