npm ci: package.json and package-lock.json are not in sync

Quick fix

Read the commands before running them. Anything that restarts a service, deletes data or changes permissions should be tried on a non-production system first.

# Locally, regenerate and commit the lockfile
npm install
git add package-lock.json && git commit -m 'sync lockfile'

# After a merge conflict in the lockfile:
git checkout --theirs package-lock.json
npm install

# Never 'fix' this in CI by switching to npm install

How to diagnose JavaScript errors

JavaScript errors cluster into package management (resolution conflicts, lockfile drift, native build failures), asynchrony (unhandled rejections, race conditions, wrong this), and memory (the V8 heap limit, which is a fixed ceiling rather than a leak indicator on its own). Because JavaScript coerces rather than throws, many bugs surface far from their cause. undefined is not a function usually means a bad import, not a bad call.

If the quick fix above does not resolve it, work through these steps. They apply to this whole class of error, not just to this one message, which is usually what saves the time.

1. For dependency errors, read what npm actually reports as the conflicting peer requirement. Reaching for --force or --legacy-peer-deps installs a tree you have not validated.
2. Always attach a rejection handler: process.on('unhandledRejection', …) in Node, and check that every async function called from a non-async context has a .catch().
3. Raise the V8 heap only after confirming it is a genuine working-set problem: node --max-old-space-size=4096. If usage grows without bound, take a heap snapshot instead.
4. Use node --inspect with Chrome DevTools to take heap snapshots and compare allocations between two points in time.
5. For native module build failures (node-gyp), confirm Python and a C++ toolchain are present and that the Node major version matches the module's prebuilt binaries.

Tools worth reaching for

• node --inspect
• npm ls <pkg>
• node --max-old-space-size
• clinic.js
• why-is-node-running

Authoritative references

Primary documentation for this error, worth reading before applying any fix in production.

📖 docs.npmjs.com

Related JavaScript errors

• bun install: lockfile had changes, but lockfile is frozenCI runs bun install --frozen-lockfile so a build can never silently resolve different…
• Bun: Cannot find moduleBun could not resolve an import: dependencies not installed, a path/extension typo, or a…
• Deno: PermissionDenied: Requires net/read accessDeno is secure by default and blocks file, network, and env access unless explicitly granted…
• ESLint: could not find an eslint.config.js fileESLint v9 reads flat config (eslint.config.js) by default and no longer looks for…
• JavaScript: 'this' is undefined in callbackContext lost when passing method as callback. Need to bind context or use arrow function.
• JavaScript: Closure capturing wrong loop variableLoop variable captured by closure refers to final value, not value at time of creation.
• JavaScript: CORS credentials not allowedCannot use credentials with wildcard origin. CORS policy requires specific origin when using…
• JavaScript: Memory leak from event listenersEvent listeners not removed when elements destroyed, causing memory leaks.

See all 42 JavaScript errors →

Browse other categories

• HTTP 494xx client errors, 5xx server errors, redirects, headers and protocol problems.
• Database 41Connections, deadlocks, constraints, replication and memory limits.
• AI 35Rate limits, context windows, GPU memory and model-serving failures.
• Network 35Refused connections, timeouts, resets, MTU problems and port exhaustion.
• Python 35Imports, virtual environments, encoding, concurrency and dependency conflicts.
• Kubernetes 34CrashLoopBackOff, ImagePullBackOff, OOMKilled, RBAC, scheduling and storage.
• Docker 27Daemon connectivity, disk space, image pulls, ports and architecture mismatches.
• System 26Disk space, systemd units, file descriptors, OOM killer and scheduled jobs.
• Cloud 25IAM permissions, quotas, service limits and credential failures.
• Security 25JWT validation, CSRF, OAuth grants, SELinux, SSH host keys and CSP.
• TLS 24Untrusted authorities, expiry, hostname mismatch, chains and cipher negotiation.
• Frontend 23Hydration mismatches, bundler resolution, layout shift and font loading.

Something missing or wrong?

This entry is maintained by hand. If the fix is out of date, incomplete, or you have a better one, email a correction and it will be reviewed.