composer 'Your lock file does not contain a compatible set of packages' - how to fix

TL;DR

The locked package set cannot satisfy the current constraints, often a PHP version or platform requirement that moved. Run composer update to re-resolve the whole set, check the platform reqs it names, and commit the new lockfile.

Error

composer 'Your lock file does not contain a compatible set of packages'  -  how to fix

Steps

1. Read the full message: composer names the constraint that fails, often a php requirement or a platform package. Expected output: You know which requirement the locked set violates.

2. Check the runtime: php -v, and compare with the require.php bound in composer.json. Expected output: You see the platform drift, for example PHP 8.1 installed while a locked package now needs 8.2.

3. Re-resolve: composer update. Expected output: composer finds a set compatible with the current platform and constraints.

4. If the platform cannot move, constrain the offending package instead: composer require [package]:"[older constraint]", then composer update [package]. Expected output: The set resolves within the platform you have.

5. Review the diff, commit composer.lock, and confirm CI. Expected output: CI installs the compatible set cleanly.

When to use

• composer install fails with your lock file does not contain a compatible set of packages
• The PHP version or a platform extension changed under a committed lockfile
• A composer.json edit made the old locked set impossible

When not to use

• The message is the simpler lock file is not up to date; use update --lock instead
• The install fails downloading packages; that is network
• A single package version is wrong; a targeted update may suffice

Variant phrasings

Incompatible set after upgrading PHP on the server

The platform shape; the lockfile was resolved for the old PHP.

composer install fails on platform reqs in CI

CI's PHP differs from dev; align the platform or the lockfile.

Lockfile incompatible after a major constraint edit

The manifest shape; a full update re-resolves the new constraint set.

Why it happens

The lockfile pins exact versions, but those pins were chosen under the platform and constraints of the last resolve. When PHP moves, a platform extension vanishes, or composer.json tightens a bound, the old pins can become jointly impossible. Only a fresh resolve can find a set that satisfies everything at once.

Edge cases

• composer update re-resolves everything and can move many packages; review the diff carefully.
• The platform check can be faked with config.platform in composer.json; use it deliberately, not to hide drift.
• Docker images that install then switch PHP versions are a classic trigger; resolve in the final image.

Provenance

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