composer 'The lock file is not up to date with the latest changes in composer.json' - how to fix

TL;DR

composer.json changed without a lockfile refresh. Run composer update --lock to re-resolve just the lockfile hash, or a full composer update if versions should move too, then commit composer.lock. CI keeps running composer install.

Error

composer 'The lock file is not up to date with the latest changes in composer.json'  -  how to fix

Steps

1. Validate first: composer validate. Expected output: You see whether composer.json itself is well-formed.

2. Refresh the lockfile: composer update --lock. Expected output: composer.lock is rewritten to match composer.json without moving versions unnecessarily.

3. If versions should move with the change, run composer update [package] instead. Expected output: The named package updates and the lockfile records it.

4. Review the diff: git diff composer.lock. Expected output: The diff matches the composer.json change.

5. Commit both files; confirm CI's composer install goes green. Expected output: Deterministic installs from the committed lockfile.

When to use

• composer install fails with the lock file is not up to date with the latest changes in composer.json
• Someone edited composer.json and skipped the lock step
• A merge changed composer.json without refreshing the lock

When not to use

• composer reports the lock file does not contain a compatible set; that is a solver problem, needs a real update
• The install fails downloading; that is network, not staleness
• You are tempted to run composer update in CI; commit the lockfile instead

Variant phrasings

composer install warns the lock file is not up to date

The warning shape; --lock refreshes without a full re-resolve.

Lockfile drift after editing composer.json by hand

The hand-edit shape; update --lock reconciles the pair.

Agent edited composer.json and CI broke

Add the lock refresh to the agent's bump routine.

Why it happens

composer.lock records a content hash of composer.json. Any edit to the manifest invalidates the hash, and composer install refuses to proceed on a lockfile that no longer describes the manifest. update --lock re-hashes and re-resolves minimally.

Edge cases

• composer update --lock still re-resolves metadata; it is not a pure hash rewrite, so review the diff.
• If the composer.json edit was a mistake, revert it instead of re-locking around it.
• Partial updates (composer update [package]) keep the rest of the lock stable; prefer them for single bumps.

Provenance

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