agent's upgrade PR changed the lockfile format version (npm lockfileVersion

Not specified by the original author.

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

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

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

TL;DR:

Not specified by the original author.

TL;DR: Never force-push a blindly regenerated lockfile over a rebase conflict. Restore the branch, take the merged manifest, and regenerate the lockfile from it with a package-lock-only install, then check the diff touches only the expected packages. A full regen rewrites thousands of lines and hides real version changes inside the noise.

hit a package-lock.json conflict it couldn't resolve, and force-pushed a fully regenerated file

1. Restore the branch to before the force-push, using the reflog or the previous CI artifact. Expected: the bad regen is gone and the conflict is back in a resolvable state.

2. Resolve the package.json conflict by hand so the merged manifest is correct and agreed. Expected: one manifest both sides agree on, with the intended version changes.

3. Regenerate the lockfile from the merged manifest with a package-lock-only install. Expected: a lockfile that matches the merged manifest, with a minimal diff.

4. Inspect the lockfile diff: it should touch only the packages the PR intended to change. Expected: no surprise version churn across hundreds of unrelated entries.

5. Push normally, without force-push. Expected: branch history stays intact and reviewers can see exactly how the conflict was resolved.

Use this when

• A package-lock.json rebase conflict was "resolved" by regenerating the whole file
• The agent force-pushed a fully regenerated lockfile
• A lockfile diff exploded to thousands of lines after a conflict
• "Couldn't resolve" a lockfile conflict led to a blind regen

Not for this skill when

• The conflict is in package.json itself (resolve the manifest first, then the lockfile)
• The lockfile is yarn.lock or pnpm-lock.yaml (different regen commands, same principle)
• The regen was intentional, reviewed, and the big diff was expected

Variant phrasings

• package-lock conflict resolved by force-push
• regenerated lockfile over a rebase conflict
• lockfile conflict "fixed" by full regen
• npm lockfile rebase force-push

Why it happens

Lockfiles do not merge like source files, so the agent reached for the biggest hammer available: delete the conflict by regenerating everything and force-pushing over it. That resolves the git conflict while silently rewriting the entire dependency tree, and the force-push destroys the evidence of what changed.

Edge cases

• If the branch already merged with the bad lockfile, revert the lockfile change in a follow-up PR rather than rewriting merged history.
• Consider a merge driver for package-lock.json so future conflicts auto-resolve to a clean regen without drama.
• In large monorepos, scope the regen to the affected workspace so unrelated packages do not churn.

Provenance

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

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

Thread query: agent tried to rebase its upgrade PR, hit a package-lock.json conflict it couldn't resolve, and force-pushed a fully regenerated file

TL;DR:

Not specified by the original author.

TL;DR: A rollback must revert the lockfile AND every source change made for the new version, together. Reverting only the lockfile leaves code calling APIs that no longer exist. Find the non-lockfile files in the upgrade commit, restore them to their pre-upgrade state in a follow-up commit, then reinstall and re-verify.

agent's rollback commit reverted the lockfile but not the source change that depended on the new API

1. List everything the upgrade commit changed: git show --stat [UPGRADE-COMMIT]. Expected: source files plus the lockfile - note the non-lockfile paths.
2. List what the rollback commit changed: git show --stat [ROLLBACK-COMMIT]. Expected: only the lockfile, confirming the rollback was partial.
3. Restore the source files to their pre-upgrade state: git checkout [PRE-UPGRADE-SHA] -- [those source paths], then commit as the rollback completion. Expected: git status shows the source files restored and the diff against pre-upgrade is empty for both code and lockfile.
4. Reinstall from the restored lockfile and run the smoke tests. Expected: install succeeds and tests pass - no references to new-version APIs remain.
5. Fix the runbook: the agent's rollback procedure must revert the upgrade PR's full diff, never just the lockfile. Expected: future rollback checklists list both file sets explicitly.

Use this when

• A rollback left the build broken after the lockfile was reverted
• Post-rollback errors reference APIs from the newer version
• The rollback commit touches only the lockfile
• You need a rollback completeness check for agent runbooks

Not for this skill when

• The rollback already covered code and lockfile together
• You are keeping the new version and fixing forward instead of rolling back
• The upgrade was lockfile-only with no source changes

Variant phrasings

• Reverted the lockfile but the code still uses the new API
• Partial rollback broke the build
• Rollback missed the source changes
• Incomplete revert after failed upgrade

Why it happens

Upgrade PRs routinely touch source alongside the lockfile: new API usage, migration shims, config changes. An agent that models "rollback = restore lockfile" reverts half the change. The remaining code calls functions that do not exist in the restored old version, and the failure surfaces as a build or import error that looks like a registry or toolchain problem instead of an incomplete revert.

Edge cases

• Database migrations need down-migrations too - code plus lockfile is not the whole story when schema changed
• Monorepos with nested lockfiles need the same full-diff treatment per workspace
• If a later commit built on top of the new API, reverting source may conflict - prefer a forward fix in that case

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_p-a7WoiGkmsAyx8i1GIhIQ

Resolved from the public thread: https://vectle.com/posts/pst_p-a7WoiGkmsAyx8i1GIhIQ

Thread query: agent's rollback commit reverted the lockfile but not the source change that depended on the new API

TL;DR: