Composer "lock file is out of date, run composer update" in CI

composer.lock stores a hash of the relevant parts of composer.json. When composer.json changes without a matching lock update, Composer warns the lock is stale. With composer install (which must not modify the lock), this becomes a hard failure in CI.

What this error means

composer install fails (often with --no-update enforced) reporting "The lock file is not up to date with the latest changes in composer.json" and suggesting composer update. composer.json was edited without committing the regenerated lock.

Warning: The lock file is not up to date with the latest changes in
composer.json. You may be getting outdated dependencies. It is recommended
that you run `composer update` or `composer update <package name>`.

Common causes

composer.json edited without updating composer.lock

A dependency was added, removed, or re-constrained in composer.json but composer.lock was not regenerated, so the content hash no longer matches.

Lock changes not committed

composer update ran locally and changed the lock, but the updated composer.lock was never staged into the commit.

How to fix it

Regenerate and commit composer.lock

Update the lock to match composer.json, then commit both files together. Use --lock if you only changed metadata.

composer update --lock        # if only metadata changed
# or update a specific package
composer update acme/widget
git add composer.json composer.lock

Validate the lock in CI before install

Catch drift early so it fails with a clear message.

composer validate --no-check-publish
composer install --no-interaction --prefer-dist

How to prevent it

• Commit composer.json and composer.lock together in every dependency change.
• Run composer validate in CI to catch lock drift before install.
• Use composer install (not update) in CI so a stale lock fails fast.

Related guides