How to fix npm ERR! code ECILOCKFILE npm ERR! The package-lock.json file must be present for `npm ci` in npm

npmBEGINNERLOWUpdated Dec 3, 2025· 171 views

This error occurs when running npm ci without a package-lock.json file. Generate the lockfile with npm install and commit it to version control.

Quick fix

Fixes npm ERR! code ECILOCKFILE npm ERR! The package-lock.json file must be present for `npm ci`

npm install
  1. Generate the lockfile
  2. Check .gitignore
  3. Commit the lockfile
  4. Verify in CI
npm — error
npm install
npm ERR! code ECILOCKFILE
npm ERR! The package-lock.json file must be present for `npm ci`
shell
npm install

What this error means

npm ci (clean install) is designed for continuous integration environments where reproducible builds are essential. It requires package-lock.json to exist because it installs exactly the versions specified in the lockfile. Without a lockfile, npm ci cannot guarantee reproducible builds - different runs might install different versions of transitive dependencies, potentially causing subtle bugs. This error usually means package-lock.json is either missing from the repository or excluded by .gitignore.

Typical symptoms

  • CI/CD pipeline fails immediately at npm ci step
  • Error code ECILOCKFILE in npm output
  • Fresh git clone followed by npm ci fails
  • Works locally because lockfile exists but fails in CI
  • Lockfile mysteriously missing after git operations

Common causes

  1. package-lock.json was never committed to the repository
  2. package-lock.json is listed in .gitignore
  3. Developer used npm install but forgot to commit the lockfile
  4. Repository was created from a template without lockfile
  5. Lockfile deleted accidentally during cleanup

How to fix "npm ERR! code ECILOCKFILE npm ERR! The package-lock.json file must be present for `npm ci`"

1Generate the lockfile

Create package-lock.json:

bash
npm install

This generates package-lock.json based on your package.json.

2Check .gitignore

Ensure package-lock.json is NOT in .gitignore:

bash
grep "package-lock" .gitignore

If found, remove the line. The lockfile SHOULD be committed.

bash
# Remove from .gitignore if present
sed -i '/package-lock/d' .gitignore
3Commit the lockfile

Add and commit:

bash
git add package-lock.json
git commit -m "Add package-lock.json for reproducible builds"
git push
4Verify in CI

Your CI pipeline should now work:

yaml
# Example GitHub Actions
- name: Install dependencies
  run: npm ci

npm ci will use the committed lockfile for reproducible installs.

Advanced notes

Why commit package-lock.json?

1. Reproducibility: Everyone gets identical dependency trees
2. Security: Lockfile captures audited versions
3. Speed: npm ci is faster than npm install
4. Debugging: You can see exactly what changed between commits

For libraries (packages you publish to npm), some teams prefer not to commit lockfiles since consumers use their own resolution. But for applications, always commit it.

If you're using yarn instead of npm, commit yarn.lock:

bash
git add yarn.lock

If you're using pnpm, commit pnpm-lock.yaml:

bash
git add pnpm-lock.yaml

For monorepos, ensure the lockfile is at the root and covers all workspaces.

Frequently asked questions

What does "npm ERR! code ECILOCKFILE npm ERR! The package-lock.json file must be" mean?
npm ci (clean install) is designed for continuous integration environments where reproducible builds are essential. json to exist because it installs exactly the versions specified in the lockfile. Without a lockfile, npm ci cannot guarantee reproducible builds - different runs might install different versions of transitive dependencies, potentially causing subtle bugs.
How do I fix "npm ERR! code ECILOCKFILE npm ERR! The package-lock.json file must be"?
This error occurs when running npm ci without a package-lock.json file. Generate the lockfile with npm install and commit it to version control.
What causes "npm ERR! code ECILOCKFILE npm ERR! The package-lock.json file must be"?
package-lock.json was never committed to the repository package-lock.json is listed in .gitignore Developer used npm install but forgot to commit the lockfile
Is the "npm ERR! code ECILOCKFILE npm ERR! The package-lock.json file must be" error serious?
It is a low-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading