## 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

```text
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