{"record":{"id":"244c7bb52ced4008","repo":"getgrav/grav","slug":"following-requirements-have-failed","errorCode":null,"errorMessage":"Following requirements have failed:","messagePattern":"Following requirements have failed:","errorType":"validation","errorClass":"RuntimeException","httpStatus":null,"severity":"critical","filePath":"system/src/Grav/Installer/Install.php","lineNumber":258,"sourceCode":"                    $errors .= <<<ERR\nNote: Your CLI PHP version may differ from your web server's PHP version.\nIf your web server runs PHP 8.3+, upgrade via the Admin panel instead.\nOr configure your hosting to use PHP 8.3 for CLI (check your hosting control panel).\nYou can also try: php8.3 bin/gpm self-upgrade\n\nERR;\n                }\n\n                $errors .= <<<ERR\nPlease install Grav 1.7.51 first by running following commands:\n\nwget -q https://getgrav.org/download/core/grav-update/1.7.51 -O tmp/grav-update-v1.7.51.zip\nbin/gpm direct-install -y tmp/grav-update-v1.7.51.zip\nrm tmp/grav-update-v1.7.51.zip\nERR;\n            }\n\n            throw new RuntimeException($errors);\n        }\n\n        $this->prepare();\n        $this->install();\n        $this->finalize();\n    }\n\n    public function setProgressCallback(?callable $callback): self\n    {\n        $this->progressCallback = $callback;\n\n        return $this;\n    }\n\n    private function relayProgress(string $stage, string $message, ?int $percent = null): void\n    {\n        if ($this->progressCallback) {\n            ($this->progressCallback)($stage, $message, $percent);","sourceCodeStart":240,"sourceCodeEnd":276,"githubUrl":"https://github.com/getgrav/grav/blob/6040efed04efa69b8209448ed81308e7c24147c2/system/src/Grav/Installer/Install.php#L240-L276","documentation":"Install::run() (used by `bin/gpm direct-install`) first verifies environment requirements — PHP version, required PHP extensions, write permissions — and accumulates every failure into a multi-line `$errors` message before throwing RuntimeException with that text. When the currently installed Grav is too old, the message also embeds the exact two-step instructions: first install 1.7.51 via the grav-update zip, then retry. The exception message is the diagnosis; nothing has been installed when it throws.","triggerScenarios":"Running `bin/gpm direct-install <zip>` on a server whose PHP version is below the package's requirement; a required extension (e.g. ctype, curl, mbstring, yaml) not loaded; upgrading from a Grav older than the supported upgrade path, which demands the intermediate 1.7.51 step; insufficient write permissions on the install target.","commonSituations":"Shared hosting with an old PHP CLI on PATH while the web server runs a newer PHP (gpm uses the CLI one); servers missing non-default extensions; long-lived sites jumping several major versions in one direct-install.","solutions":["Read the full thrown message — it itemizes exactly which requirements failed","Fix each listed item: switch the CLI PHP (e.g. `php8.2 bin/gpm ...`), install missing extensions, correct permissions","If the message shows the 1.7.51 instructions, run that intermediate step first: `wget -q https://getgrav.org/download/core/grav-update/1.7.51 -O tmp/grav-update-v1.7.51.zip && bin/gpm direct-install -y tmp/grav-update-v1.7.51.zip`, then retry the newer package","Verify you downloaded the correct grav-update package for your channel"],"exampleFix":"# before\nphp bin/gpm direct-install tmp/grav-update-v1.8.0.zip   # CLI php is 7.4 -> requirements fail\n\n# after\nphp8.2 bin/gpm direct-install tmp/grav-update-v1.8.0.zip # use a CLI PHP matching the requirement","handlingStrategy":"validation","validationCode":"// Pre-flight before direct-install\n$requiredPhp = '8.2.0'; // from the package you are installing\nif (version_compare(PHP_VERSION, $requiredPhp, '<')) {\n    fwrite(STDERR, 'PHP ' . $requiredPhp . '+ required, running ' . PHP_VERSION . PHP_EOL);\n    exit(1);\n}\nforeach (['ctype','curl','dom','json','mbstring','openssl','session','simplexml','xml','zip'] as $ext) {\n    if (!extension_loaded($ext)) {\n        fwrite(STDERR, \"Missing extension: {$ext}\" . PHP_EOL);\n        exit(1);\n    }\n}\nif (!is_writable(GRAV_ROOT)) {\n    fwrite(STDERR, 'GRAV_ROOT not writable' . PHP_EOL);\n    exit(1);\n}","typeGuard":null,"tryCatchPattern":"try {\n    Install::instance()->run();\n} catch (\\RuntimeException $e) {\n    // 'Following requirements have failed:' — the message lists every failed item\n    fwrite(STDERR, $e->getMessage());\n    exit(1); // fix environment, then re-run; nothing was installed\n}","preventionTips":["Check `php -v` on the CLI binary gpm will use — it often differs from the web SAPI","Validate PHP version and extensions against the target release notes before downloading the update","On very old sites, plan the two-step hop through 1.7.51 rather than one jump","Run requirements checks in CI/deploy scripts so failures surface before a maintenance window"],"tags":["installer","requirements","php-version","upgrade","grav"],"backgroundTag":"system-requirements-not-met","analyzedSha":"6040efed04efa69b8209448ed81308e7c24147c2","analyzedAt":"2026-08-17T05:07:31.593Z","schemaVersion":2},"datasetVersion":"2026-08-17T09:17:11.063Z"}