npm ERR! code 1: why the build failed with exit code 1
npm ERR! code 1 (npm error code 1 in newer npm) only says that a script npm ran exited with code 1. The real error is printed above it: usually a compile or type error, a lockfile out of sync with package.json, or a dependency whose install script failed. Find the first error line above code 1, fix that, and the build passes.
By Livops team, the people who build and run LivopsUpdated
The line people search for, and what surrounds it in a failed build:
npm ERR! code 1
npm ERR! path /app
npm ERR! command failed
npm ERR! command sh -c next build
Newer npm prints the same lines as npm error code 1. This page explains what the code means, lists the real causes from the most common, shows how to reproduce the server’s build on your machine, and says what Livops does when a build fails this way.
What does the error mean?
npm runs each script by passing it to /bin/sh, and if the script exits with a code other than 0, npm aborts the process[1]. code 1 is that script’s own exit code. The command line names what failed, and the path line says where: a folder inside node_modules means a dependency’s install script failed; your project’s root means your own build (or postinstall) script did.
npm also writes everything to a debug log and prints its path when a command fails[2]. The cause is almost never in the npm lines themselves. Scroll up to the first line that says error.
Causes, most common first
1. The build itself failed: a compile, type or import error
Above code 1 you see something like error TS2345, Type error:, Module not found: Can't resolve './Header' or SyntaxError. Run the same command locally and it stops in the same place:
npm run build
A frequent case: the import’s case differs from the file name. macOS and Windows find ./header when the file is Header.tsx; Linux, where the server builds, does not. Rename it with Git so the change is committed:
git mv src/components/header.tsx src/components/Header.tsx
2. package-lock.json does not match package.json
npm ci needs an existing package-lock.json, and when the lockfile and package.json disagree it exits with an error instead of updating the lockfile[3]. You added a dependency and committed only package.json. Fix it locally and commit both:
npm install
git add package.json package-lock.json
3. A dependency’s install script failed
The path points into node_modules, and above it you see gyp ERR! or node-pre-gyp. The package compiles C++ on install and the machine has no compiler, or it has no prebuilt binary for your Node version. Use a prebuilt alternative (bcryptjs instead of bcrypt), update the package to a version that ships binaries for your Node, or build from a Dockerfile that installs python3, make and g++. npm hides install scripts’ output since v7; set foreground-scripts to see it[2].
4. A different Node version
The code or a package needs a newer Node than the server has: SyntaxError: Unexpected token, ERR_REQUIRE_ESM, or The engine "node" is incompatible. Say which Node you need in engines[4] and pin the same version locally:
{
"engines": { "node": ">=22" }
}
5. A variable the build reads is missing
Next.js, Vite and SvelteKit put some variables into the code while building. If process.env.API_URL is undefined at build time, code that throws on it ends the build with code 1. Set the variable in the build environment, not only at runtime.
6. The build ran out of memory
If the lines above say JavaScript heap out of memory, or the exit code is 137 rather than 1, it is memory, not code. See JavaScript heap out of memory during next build.
How to confirm the fix locally
Build the way a server does: from a clean install, with the lockfile, on Linux.
rm -rf node_modules
npm ci --foreground-scripts
npm run build
echo "exit code: $?"
To catch case-sensitive imports and Linux-only failures on a Mac or Windows machine, run the same in a container with the server’s Node version:
docker run --rm -v "$PWD":/app -w /app node:22 sh -c "npm ci && npm run build"
exit code: 0 there means the build will pass for the same reason.
On Livops
- Two codes, depending on where it failed. A failed
npm installornpm ciisinstall_failed; a failed build command isbuild_failed. Either way the previous version keeps running. See Install failed and Build failed. - A Tip line for the errors Livops recognises. The build log ends with a Tip: line when it finds one of these:
ERESOLVE(it suggestsnpm install --legacy-peer-deps),gyp ERR! find Python(switch to a prebuilt package or add a Dockerfile), a TypeScripterror TS,E401from a private registry (put the token in Variables and use it in.npmrc),EBADDEVENGINES(Livops builds with Node 22 and 24), andJavaScript heap out of memory. - Node version. Livops reads
.nvmrc,.node-versionanddevEnginesinpackage.json. - The assistant explains, you decide. Next to the failed build, the assistant’s button reads the log and says what happened and how to fix it. When the build stopped on a missing variable, it can take you to Variables with a row for that name. Anything it proposes is a card that does nothing until you press it.
The full list of codes is in Deploy errors.
Questions
What does exit code 1 mean in npm?
It is the exit code of the command npm ran for you, such as next build or tsc, not an npm problem. Any non-zero exit makes npm stop and print code 1 or whatever code the command returned. The cause is in the lines above.
Where is the full npm log?
When a command fails, npm prints the path of its debug log, by default in the _logs folder of the npm cache. Run the command with --loglevel verbose, or npm ci --foreground-scripts, to see more.
It builds on my laptop. Why not on the server?
The usual differences are a file name whose case differs from the import (Linux file systems are case-sensitive), a different Node version, a lockfile you did not commit, or a variable that exists only in your local .env.
Should I use npm install or npm ci in a deploy?
npm ci when package-lock.json is committed: it installs exactly the lockfile and fails if package.json disagrees with it, so the server gets what you tested. npm install may update the lockfile instead.
What does Livops show for this error?
The deploy fails as install_failed or build_failed, the previous version keeps running, and the build log ends with a Tip line when the error is one Livops recognises. The assistant can read the log and explain it.
Sources
- npm Docs — scripts (docs.npmjs.com). Checked .
- npm Docs — Logging (docs.npmjs.com). Checked .
- npm Docs — npm ci (docs.npmjs.com). Checked .
- npm Docs — package.json (engines) (docs.npmjs.com). Checked .
Put your project online today
Connect GitHub or drop a folder. No card is asked for.
Deploy your Node appRelated
- JavaScript heap out of memory during next build: how to fix itNode's JavaScript heap reached its limit while Next.js was building, and V8 stopped the process. Raise the heap limit with NODE_OPTIONS=--max-old-space-size, staying below the memory the build really has, and cut what the build holds in memory: source maps, type checking during the build, and heavy dependencies.
- Error: listen EADDRINUSE: address already in use — how to fix itYour server tried to listen on a port that another process on the same machine already holds. On your computer, stop the old process, usually a dev server still running in another terminal. In a deploy, it almost always means the app starts its server twice, or two processes in one container ask for the same port.
- App not listening on $PORT: why the health check failed after deployThe platform started your app, tried the port it gave it, and nothing answered in time. Almost always the app listens on its own fixed port instead of the PORT variable, listens on localhost (127.0.0.1) instead of 0.0.0.0, or crashed or was still starting when the check gave up. Listen on 0.0.0.0 and the port in PORT, and it passes.