NPM Bug: Package Lock Version Mismatch

Dec 5, 2025 by Admin 39 views

Hey folks! Let's dive into a tricky little issue that's been popping up with npm, specifically concerning the package-lock.json file. We're talking about a bug where, get this, the old version number sticks around in your lock file even after you've removed it from your package.json. Yeah, you heard that right. It’s a bit of a head-scratcher, and it can definitely mess with your build consistency if you're not careful. We've seen this happen on the latest npm versions, so it's definitely something worth understanding.

The Core Problem: Stale Lock File Data

So, what's the deal here? Basically, if you have an existing package-lock.json with a specific version number for a package, and then you go and remove that version number from your package.json, running npm install doesn't clean up the lock file. Instead, it keeps that old version number hanging around like a stubborn stain. This means your package-lock.json is lying to you, showing a version that simply doesn't exist in your project's actual definition. This is a huge bummer because the whole point of package-lock.json is to ensure consistent installs across different environments and times. When it's holding onto outdated info, it defeats its own purpose. We want our lock files to be accurate reflections of our project's dependencies, not a history lesson of what used to be there. This bug impacts the reliability of reproducible builds, which is super critical for any serious development. Imagine deploying an app and finding out it's using a version of a dependency that you explicitly removed from your project definition – that's the kind of chaos this bug can introduce. It's not just a minor visual glitch; it's a functional problem that can lead to unexpected behavior in your applications.

What Should Be Happening: Clean Slate

Here's the deal, guys: the expected behavior is pretty straightforward. If you update your package.json to remove a version number for a package, then after running npm install, that version number should be zapped from the package-lock.json too. It should be a clean slate, reflecting the current state of your package.json. Think about it: if you have a package with no dependencies and no version number specified, the package-lock.json generated from scratch should be clean. Now, if you add a version number, install it, and then decide to remove it again, the resulting package-lock.json should ideally look identical to that initial clean state. This symmetry is important for predictability. It ensures that removing version information truly reverts the lock file to a state consistent with a versionless package definition, rather than leaving behind remnants of previous states. This consistency is key for developers who might be experimenting with versioning strategies or refactoring their projects. The lock file should accurately represent the current desired state, not a blend of past and present. We're talking about accuracy and reliability here, and the current behavior just isn't cutting the mustard. Developers rely on these tools to be predictable, and when they aren't, it breeds frustration and makes debugging a nightmare. The goal is a single source of truth, and right now, the package-lock.json is failing in that regard when this bug is triggered.

Let's See It in Action: The Steps to Reproduce

To really get a handle on this, let's walk through the exact steps that trigger this annoying bug. It's a pretty simple sequence, and you can try it yourself:

Start Clean: First up, create a package.json file with no version and absolutely no dependencies. It should look something like this:
```
{
  "name": "test-package",
  "private": true,
  "description": "A test package",
  "license": "UNLICENSED",
  "author": "test author"
}
```
This is our baseline, the pristine state.
Initial Install: Now, run this command to generate a package-lock.json based on this versionless setup:
```
npm install --package-lock-only
```
As you'd expect, the resulting package-lock.json will be clean, with no version number mentioned. Like so:
```
{
  "name": "test-package",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "test-package",
      "license": "UNLICENSED"
    }
  }
}
```
Perfect. Exactly what we want at this stage.

Add a Version: Next, let's add a version number to our package.json. Change it to include the "version": "1.0.0" line:

{
  "name": "test-package",
  "version": "1.0.0",
  "private": true,
  "description": "A test package",
  "license": "UNLICENSED",
  "author": "test author"
}

Install Again: Run the install command once more:

npm install --package-lock-only

And voilà! The package-lock.json now correctly reflects the version:

{
  "name": "test-package",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "test-package",
      "version": "1.0.0",
      "license": "UNLICENSED"
    }
  }
}

So far, so good. Everything is behaving as expected.

Update the Version: Let's bump that version number up. Change package.json to:

{
  "name": "test-package",
  "version": "1.0.1",
  "private": true,
  "description": "A test package",
  "license": "UNLICENSED",
  "author": "test author"
}

Install After Update: Run the install command again:

npm install --package-lock-only

And yup, the lock file gets updated with the new version. This is all normal stuff:

{
  "name": "test-package",
  "version": "1.0.1",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "test-package",
      "version": "1.0.1",
      "license": "UNLICENSED"
    }
  }
}

The Crucial Step: Remove the Version: Now for the moment of truth. We're going to revert package.json back to its original, versionless state:
```
{
  "name": "test-package",
  "private": true,
  "description": "A test package",
  "license": "UNLICENSED",
  "author": "test author"
}
```
The Final Install (and the Bug): Run the install command one last time:
```
npm install --package-lock-only
```

The Unexpected Outcome

Here’s where things go sideways. According to the expected behavior, this last step should have updated package-lock.json to remove the version number, making it look exactly like it did in step 2. But that’s not what happens, guys. Instead, you'll find that package-lock.json still stubbornly contains the version number 1.0.1:

{
  "name": "test-package",
  "version": "1.0.1",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "test-package",
      "version": "1.0.1",
      "license": "UNLICENSED"
    }
  }
}

See? The version number is still there, even though we explicitly removed it from package.json. This is the bug in action, leaving stale data in your lock file.

Your Environment Details

Just so you know, this behavior was observed on:

npm version: 11.6.4
Node.js version: 24.11.1
Operating System: Ubuntu 24.04.3 LTS

And here's a peek at the npm config:

; node bin location = /usr/local/bin/node
; node version = v24.11.1
; npm local prefix = /home/some-user
; npm version = 11.6.4
; cwd = /home/some-user
; HOME = /home/some-user
; Run `npm config ls -l` to show all defaults.

Hopefully, with these steps and details, the npm team can get this squashed soon! It’s a small thing, but consistency in our tooling is super important for everyone’s sanity. Keep an eye on those lock files, folks!