# TL;DR

Regenerate the lockfile with the npm version the team actually uses, so the format version stays put, and pin the npm version in the agent's environment. Check the `lockfileVersion` field at the top of package-lock.json and compare `npm --version` between the agent and the team. The agent ran a newer npm than everyone else, and npm 9+ writes lockfileVersion 3 while npm 7/8 write version 2.

## Error

```text
agent's upgrade PR changed the lockfile format version (npm lockfileVersion 2 to 3) and every other PR started conflicting
```

## Steps

1. Confirm the format change. Open package-lock.json and read the `lockfileVersion` field, then check git history for when it changed. Expected: it flipped from 2 to 3 in the agent's PR.
2. Find the npm version mismatch. Run `npm --version` in the agent's environment and compare with what the team uses. Expected: the agent used npm 9 or newer while the team is on npm 7 or 8.
3. Regenerate with the team's npm. Using the correct npm major, run `npm install --package-lock-only`. Expected: the lockfile is rewritten at lockfileVersion 2 with no dependency changes, just the format fix.
4. Commit only the format fix. Verify the diff touches the lockfileVersion field and not version pins, then commit and push. Expected: other PRs can rebase cleanly again.
5. Pin the npm version for the agent. Set the agent's environment to the team's npm major (via the CI setup step or a documented version) so it cannot silently upgrade the format again. Expected: future agent runs produce lockfiles at the agreed version.

## Use this when

- A PR diff shows lockfileVersion changing with no team decision behind it
- Every open PR suddenly conflicts on package-lock.json
- The agent's environment runs a different npm major than the team
- You need to decide whether to adopt lockfileVersion 3 deliberately

## Not for this skill when

- The team already agreed to move to lockfileVersion 3 - then the fix is to rebase everyone, not revert
- Conflicts come from version changes, not the format version - resolve those normally
- You use pnpm or yarn - their lockfile formats have their own versioning rules

## Variant phrasings

- package-lock.json lockfileVersion changed unexpectedly
- npm 9 rewrote my lockfile to version 3
- agent upgraded the lockfile format and broke other PRs
- lockfile conflicts after an automated dependency bump

## Why it happens

npm ties the lockfile format to the npm major version: npm 7 and 8 write lockfileVersion 2, npm 9+ writes lockfileVersion 3. Agents often run whatever npm shipped with their base image, which drifts ahead of the team's pinned version. The rewrite is silent - `npm install` just does it - so the agent never realizes it reformatted the file.

## Edge cases

- lockfileVersion 3 is backwards compatible with npm 7+ for reading, so adopting it deliberately is fine as long as nobody is stuck on npm 6.
- If the team wants to move to v3 on purpose, do it in one dedicated PR with everyone rebasing after, not smuggled inside an upgrade PR.
- Watch for the reverse: an agent on old npm downgrading a v3 lockfile to v2, which loses information.
- Some CI caches key on the lockfile hash, so a format rewrite invalidates every cache - another reason to keep the format stable.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_N8SuL03eEkNVLhsowlZEmA