PHP error guide

Application requires a newer PHP runtime: meaning and fix

fatal server Affects: PHP 7.4–8.4 Last verified:

Error summary

Run the application under a supported site-specific PHP version or deploy a release that supports the installed runtime.

What it means

Run the application under a supported site-specific PHP version or deploy a release that supports the installed runtime.

What the error means

An application platform check rejects the executing PHP version before normal bootstrap, independently of dependency installation.

Why PHP produces it

Deployment selected a runtime older than the application’s declared minimum, often because CLI and web pools point to different versions.

PHP version notes

The behavior described for Application requires a newer PHP runtime applies to PHP 7.4–8.4 unless a narrower version is stated; exact wording can vary by SAPI and patch release.

Most common causes

  • The virtual host still targets an older FPM socket.
  • CLI deployment checks use a newer binary than production FPM.
  • The application was upgraded without its runtime prerequisite.

Minimal examples

BAD — reproduces the problem

php 
// Delete the platform check and continue on PHP 8.1

FIXED — safer pattern

php 
if (PHP_VERSION_ID < 80200) { throw new RuntimeException("PHP 8.2+ required"); }

Step-by-step diagnosis

  1. Read PHP_VERSION from the affected SAPI.
  2. Inspect the site’s FPM socket or handler mapping.
  3. Compare the application’s documented minimum with every worker and CLI job.

Fixes

Align only the affected application runtime

Select a supported pool for this site and verify extensions before traffic cutover.

php 
<?php
if (PHP_VERSION_ID < 80200) {
    throw new RuntimeException("PHP 8.2+ required");
}

Common mistakes when fixing it

  • Removing the platform guard.
  • Changing the global server PHP version without checking other sites.
  • Verifying only php -v while the website uses FPM.

How to prevent it

  • Declare and verify minimum PHP versions in deployment checks.
  • Use site-specific pools.
  • Test upgrades on the target runtime before release.

Web server / environment notes

fpm, apache, cli, shared-hosting. Every SAPI serving the application must meet its runtime contract.

Tags: fpm,apache,cli,shared-hosting

Categories