Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

The app dies at start-up because the lock file needs a newer PHP than the one running

ErrorComposer detected issues in your platform:

Short answer

Composer writes vendor/composer/platform_check.php, and every request or script that loads the autoloader runs it. It compares the PHP that is running with the lowest PHP your locked packages accept. Either run the app on a newer PHP, or re-lock the packages for the PHP you really have.

  • Applies to Composer 2, PHP 8.3, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    The message names two versions: the lowest one your locked packages accept, and the one that is running. Check what the lock file needs, then compare it with the PHP your terminal uses. The web server may run a different one.

    php -v
    composer check-platform-reqs --lock
    composer show --platform
  2. 2Match what you see, then jump to its fix

    1. 1composer install works in your terminal, but the site or a queue worker fails and the 'You are running' version is lower than php -v.The web server, worker or cron job runs an older PHP than the lock file needsFix
    2. 2Your laptop or CI runs a newer PHP than the server, and the error appeared after a composer update there.The lock file was resolved on a newer PHP than production runsFix
    3. 3The upgrade is planned but not possible today, and the requirement named in the message is the only thing stopping the app.You must keep the older PHP for a short while (temporary workaround)Fix

What does the error look like?

  • Composer detected issues in your platform:
  • Your Composer dependencies require a PHP version ">= 8.2.0". You are running 8.1.2.
  • HTTP/1.1 500 Internal Server Error (on every page, sent before the message)

Cause 1 of 3

The web server, worker or cron job runs an older PHP than the lock file needs

1Check

The check file runs inside whichever PHP loads vendor/autoload.php, so it reports the version of that process, not of your shell. Print the version and SAPI that the web process really uses.

echo '<?php echo PHP_VERSION, " ", PHP_SAPI;' > public/version.php
curl -s https://example.com/version.php
rm public/version.php

2Fix

Point the web server, the queue worker and the cron entry at a PHP that meets the version in the message, then restart them. With PHP-FPM that means sending requests to the pool of the newer version.

# nginx: use the listen address of the pool you need
location ~ \.php$ {
    fastcgi_pass unix:/path/to/pool-for-the-newer-php.sock;
}

3Verify

The small version file now prints the required PHP, and the site loads without the 500.

curl -sI https://example.com/ | head -n 1

Confirmed by raw.githubusercontent.com

Did this fix it?

Cause 2 of 3

The lock file was resolved on a newer PHP than production runs

1Check

composer.lock holds the package versions Composer chose on the machine where it ran. If it chose releases that need PHP 8.2, the generated check refuses to start on PHP 8.1. See whether a config.platform entry exists in composer.json.

composer check-platform-reqs --lock
grep -n -A3 '"platform"' composer.json

2Fix

Tell Composer which PHP production runs, so it picks releases that PHP accepts, then re-resolve the lock file. Composer warns that a faked platform also stops it from checking dependencies on its own, so run the platform check on the real server as well. Upgrading the server instead is the cleaner way out.

{
    "config": {
        "platform": { "php": "8.1.0" }
    }
}

composer update

3Verify

Run the check on the production server with the production PHP.

composer check-platform-reqs

Confirmed by getcomposer.org

Did this fix it?

Cause 3 of 3

You must keep the older PHP for a short while (temporary workaround)

1Check

The php check is on unless platform-check is false, and a build made with --ignore-platform-reqs does not write the check file at all. Confirm what your composer.json sets.

composer config platform-check

2Fix

Switch the check off in composer.json and regenerate the autoloader. This hides the guard, not the problem: a package that really needs the newer PHP can still break at run time. Turn it back on after the upgrade.

{
    "config": {
        "platform-check": false
    }
}

composer dump-autoload

3Verify

The autoloader stops loading the check, so the site boots again.

curl -sI https://example.com/ | head -n 1

Confirmed by getcomposer.org

Did this fix it?

How do I stop it coming back?

  • Pin config.platform.php to the PHP your production server runs, so the lock file never picks releases it cannot start.
  • Run composer check-platform-reqs in the deploy step, on the server, with the server's PHP.
  • Keep development, CI and production on the same PHP minor version.
  • Write the PHP version into the deploy notes whenever you upgrade a framework, since a new major release often raises the minimum.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.