Fixing Composer's 'Requirements Could Not Be Resolved' Error: A Diagnostic Guide

You ran composer update or composer install and got the wall of text ending in "Your requirements could not be resolved to an installable set of packages." The useful takeaway: this message is Composer's dependency solver telling you the version constraints in your project cannot all be satisfied at once. The first conflict it prints is often a symptom, not the root cause, so fixing it is a diagnostic process, not guesswork.

This guide assumes Composer 2 (check with composer --version). Composer 1's solver is slower and its conflict output is much harder to read; if you are still on Composer 1, upgrading the Composer binary itself is your first fix.

Recognizing the condition

The failure looks like this: Composer prints "Loading composer repositories", then "Updating dependencies", then aborts with the resolution error and a block of lines like vendor/package-a 2.0 requires vendor/shared ^3.0 conflicting with vendor/package-b 1.4 requires vendor/shared ^2.0. No packages are installed or changed — the solver fails before touching your vendor/ directory, so your application is not left in a half-updated state.

Cause and diagnostic table

Likely cause	How to confirm
Two packages require incompatible major versions of a shared dependency	composer why-not vendor/shared 3.0 lists every constraint blocking that version
PHP version or missing extension doesn't match requirements	composer check-platform-reqs shows unmet platform requirements
Partial update pinned transitive dependencies at stale versions	You ran composer update vendor/package without -W; the lock file holds old transitive versions
Your own root constraint in composer.json is too narrow	composer prohibits vendor/package <version> points back at your root composer.json

Ordered checks before changing anything

1. Validate the file. Run composer validate in the project root. A malformed or internally inconsistent composer.json wastes debugging time; fix any errors it reports first.
2. Check the platform. Run composer check-platform-reqs. This compares your PHP version and loaded extensions (ext-* requirements) against what the locked or resolved packages need. If this fails, the conflict is environmental, not a version-constraint problem.
3. Ask the solver why. Run composer why-not vendor/package <version-you-want> (the prohibits command is an alias). This traces exactly which constraints block the version, including transitive ones. composer show -t vendor/package shows the dependency tree if you need broader context.
4. Read the full solver output, not just the first line. Composer 2 groups conflicts; the root cause is frequently the last package mentioned or a constraint from your own root composer.json.

Fixes tied to findings

Conflicting constraints on a shared dependency

If why-not shows your root composer.json pins "vendor/shared": "^2.0" while a package you want requires ^3.0, widen your own constraint to something like "^2.5 || ^3.0" and re-run composer update vendor/shared. If the conflict is between two third-party packages, you must either upgrade/downgrade one of them to a release with a compatible constraint, or find an alternative package — you cannot edit another package's constraints.

Platform mismatch

If check-platform-reqs reports a missing extension or wrong PHP version, fix the environment: install the extension, or add a platform override in composer.json only when you genuinely deploy to a different PHP than your local machine:

{
  "config": {
    "platform": {
      "php": "8.2.14"
    }
  }
}

As a diagnostic only, you can run composer update --ignore-platform-reqs to confirm the remaining conflicts are real constraint conflicts and not platform noise. Never commit a lock file produced this way for production — it masks real runtime incompatibilities and the application will fail at runtime instead of at install time.

Stale transitive pins from a partial update

If you updated one package and hit conflicts, re-run with dependencies included: composer update vendor/package --with-dependencies (or -W). This lets Composer also move the transitive packages that the new version needs, instead of holding them at the locked versions.

Verifying the fix

After the solver succeeds, confirm reproducibility rather than trusting the green output: delete vendor/, run composer install (which installs strictly from the lock file), then composer check-platform-reqs. Review the composer.lock diff before deploying — composer update with no arguments updates everything, and unexpected upgrades hide in large diffs. Ideally, run the same install in CI with the same PHP version and extensions as production to catch platform drift.

When to escalate

Escalate beyond constraint editing when: the solver output remains unreadable after why-not (reproduce with a minimal composer.json containing only the two conflicting requires to isolate the pair); a required package is abandoned with no compatible release (evaluate a maintained fork, an alternative package, or a forked VCS repository with adjusted constraints); or you are tempted to use replace or inline aliases like dev-main as 2.0 — treat those as last resorts, because they confuse future solver runs and security audits.