npm ERR! code 1 is the generic error code for a script that exited with code 1 — the install, the build, the test, or the postinstall hook failed. The right answer is to read the actual error above the ERR! line, not the code itself. The mistake every team makes: the team re-runs npm install --force to ‘fix’ the error, the —force installs the wrong version of a dependency, the team’s app is broken in production.
Table of contents
- The 12 common causes — the actual list
- The debugging path — read the error above the ERR! line
- The native module build failure — node-gyp and the system libraries
- The engine mismatch — Node version and npm version
- The peer dependency conflict — the missing peer
- The corrupted npm cache — npm cache clean —force
- The one fix that catches half of them
- How this fits the rest of the stack
- FAQ
The 12 common causes — the actual list
The 12 common causes of npm ERR! code 1:
- Native module build failure (node-gyp, Python, MSBuild).
- Postinstall script failed (a
postinstallscript in the package or in a dependency). - Engine mismatch (Node version or npm version does not match the package’s
enginesfield). - Peer dependency conflict (a peer dep is not installed, or two peer deps conflict).
- Corrupted npm cache (
npm cache clean --forceis the fix). - Network failure (the npm registry is unreachable, or a private registry is down).
- Permission error (the team is not the owner of the file, or the directory is read-only).
- Missing system library (libssl, libpq, libxml2 — required by a native module).
- Invalid package.json (syntax error, missing field).
- Invalid lockfile (the package-lock.json is out of sync with package.json).
- Disk space or memory exhausted.
- The package does not exist on the registry (typo, unpublished package).
The debugging path — read the error above the ERR! line
The right answer is to read the error above the npm ERR! line. The actual error is in the script’s stdout/stderr, npm wraps it in ERR! code 1 and prints the code, but the actual error is the message above. The right answer for a native module failure is to read the node-gyp output (the actual compiler error is in the build output). The right answer for a postinstall script is to read the script’s stdout (the actual error is in the script’s output).
The wrong answer is to focus on the code 1. The code is a generic ‘something failed’, the actual error is in the message. The team that focuses on the code and not the message will spend an hour on the wrong fix.
The native module build failure — node-gyp and the system libraries
The native module build failure is the most common cause of npm ERR! code 1. The team installs a package that has a native dependency (e.g., bcrypt, sharp, pg-native), the build runs, the build fails because the system is missing a library (libssl, libpq) or the build tool (python3, make, g++). The right answer is to install the missing system library (apt install libpq-dev for Postgres, apt install build-essential for the build tool).
The engine mismatch — Node version and npm version
The engine mismatch is when the team’s Node version does not match the package’s engines field. The package’s package.json says "engines": { "node": ">=18" }, the team is on Node 16, the install fails. The right answer is to upgrade the Node version, the wrong answer is to use --engine-strict=false — the team is installing a package that does not support their Node version, the team’s app is broken at runtime.
The peer dependency conflict — the missing peer
The peer dependency conflict is when the package’s peerDependencies field requires another package, and the other package is not installed, or the wrong version is installed. The right answer is to install the peer dep at the version the package requires. The wrong answer is to use --legacy-peer-deps — the team is installing with a missing peer, the package may not work at runtime.
The corrupted npm cache — npm cache clean —force
The corrupted npm cache is when the team’s npm cache has a corrupted tarball, the install fails. The right answer is npm cache clean --force (or rm -rf ~/.npm for the offline version), then re-run the install. The wrong answer is to skip the cache and use --prefer-offline — the team is still using the corrupted cache.
The one fix that catches half of them
The one fix that catches half of npm ERR! code 1 is to delete node_modules and package-lock.json, then re-run npm install. The team’s existing node_modules may be in a bad state (a partial install, a corrupted symlink, a stale binary), the team’s package-lock.json may be out of sync with package.json. The right answer is to start from scratch, not to add a --force flag.
The right answer is:
rm -rf node_modules package-lock.json
npm installThe wrong answer is to add --force to a failing install. --force is not a fix, it is a way to skip the checks that the install is failing on. The team’s install ‘succeeds’ with —force, but the team’s app is broken at runtime.
How this fits the rest of the stack
The infrastructure question is a small piece of a larger pattern: the team’s runtime, storage, database, secret store, logs, and deployment platform are all parts of the same platform. The right answer is to model the full stack before the project ships, not after. The RunxBuild hosting calculator is the right place to do that exercise — pick the runtime, the memory tier, the storage, the secret store, and the egress, and the calculator shows what the deploy actually costs at the team’s actual usage.
Useful related references:
FAQ
What does npm ERR! code 1 mean?
It means a script exited with code 1 — the install, the build, the test, or the postinstall hook failed. The actual error is in the output above the ERR! line.
How do I fix npm ERR! code 1?
Read the error above the ERR! line, then fix the root cause. The right answer for half the cases is to delete node_modules and package-lock.json and re-run npm install.
What is the most common cause of npm ERR! code 1?
A native module build failure (node-gyp, missing system library). The right answer is to install the missing system library (libpq-dev for Postgres, build-essential for the build tool).
How do I clear the npm cache?
npm cache clean --force or rm -rf ~/.npm. The right answer is to clear the cache and re-run the install.
Should I use —force to fix npm errors?
No. —force is not a fix, it is a way to skip the checks that the install is failing on. The team’s install ‘succeeds’ with —force, but the team’s app is broken at runtime.
How do I install a package’s missing system library?
On Debian/Ubuntu: apt install <library>-dev. On Alpine: apk add <library>-dev. On macOS: brew install <library>. The right answer is to check the package’s README for the system requirements.
What is the difference between npm ERR! code 1 and ELIFECYCLE?
code 1 is a script that exited with code 1 (the script’s exit code). ELIFECYCLE is a more specific error for a script that failed during install (the script’s exit code is preserved in the error).
How do I see the full error from npm install?
npm install --loglevel verbose or npm install --loglevel silly. The right answer is the verbose level for most cases, the silly level for the hard ones.