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

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

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