getgrav/grav · critical · RuntimeException

Following requirements have failed:

Error message

Following requirements have failed:

What it means

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.

Source

Thrown at system/src/Grav/Installer/Install.php:258

                    $errors .= <<<ERR
Note: Your CLI PHP version may differ from your web server's PHP version.
If your web server runs PHP 8.3+, upgrade via the Admin panel instead.
Or configure your hosting to use PHP 8.3 for CLI (check your hosting control panel).
You can also try: php8.3 bin/gpm self-upgrade

ERR;
                }

                $errors .= <<<ERR
Please install Grav 1.7.51 first by running following commands:

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
rm tmp/grav-update-v1.7.51.zip
ERR;
            }

            throw new RuntimeException($errors);
        }

        $this->prepare();
        $this->install();
        $this->finalize();
    }

    public function setProgressCallback(?callable $callback): self
    {
        $this->progressCallback = $callback;

        return $this;
    }

    private function relayProgress(string $stage, string $message, ?int $percent = null): void
    {
        if ($this->progressCallback) {
            ($this->progressCallback)($stage, $message, $percent);

View on GitHub (pinned to 6040efed04)

Solutions

1. Read the full thrown message — it itemizes exactly which requirements failed
2. Fix each listed item: switch the CLI PHP (e.g. `php8.2 bin/gpm ...`), install missing extensions, correct permissions
3. 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
4. Verify you downloaded the correct grav-update package for your channel

Example fix

# before
php bin/gpm direct-install tmp/grav-update-v1.8.0.zip   # CLI php is 7.4 -> requirements fail

# after
php8.2 bin/gpm direct-install tmp/grav-update-v1.8.0.zip # use a CLI PHP matching the requirement

// Pre-flight before direct-install
$requiredPhp = '8.2.0'; // from the package you are installing
if (version_compare(PHP_VERSION, $requiredPhp, '<')) {
    fwrite(STDERR, 'PHP ' . $requiredPhp . '+ required, running ' . PHP_VERSION . PHP_EOL);
    exit(1);
}
foreach (['ctype','curl','dom','json','mbstring','openssl','session','simplexml','xml','zip'] as $ext) {
    if (!extension_loaded($ext)) {
        fwrite(STDERR, "Missing extension: {$ext}" . PHP_EOL);
        exit(1);
    }
}
if (!is_writable(GRAV_ROOT)) {
    fwrite(STDERR, 'GRAV_ROOT not writable' . PHP_EOL);
    exit(1);
}

try {
    Install::instance()->run();
} catch (\RuntimeException $e) {
    // 'Following requirements have failed:' — the message lists every failed item
    fwrite(STDERR, $e->getMessage());
    exit(1); // fix environment, then re-run; nothing was installed
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• 400
• Could not migrate the Twig-sandbox allowlists to the additiv
• Uploaded archive file is not a valid Grav update package
• Uploaded archive file is not a valid Grav update package
• Could not update system configuration to maintain backwards

AI-assisted analysis of getgrav/grav@6040efed04 (2026-08-17). Data as JSON: /api/errors/244c7bb52ced4008. Report an issue: GitHub.