{"record":{"id":"d59b0ceb640879ae","repo":"getgrav/grav","slug":"uploaded-archive-file-is-not-a-valid-grav-update-p","errorCode":null,"errorMessage":"Uploaded archive file is not a valid Grav update package","messagePattern":"Uploaded archive file is not a valid Grav update package","errorType":"console","errorClass":"RuntimeException","httpStatus":null,"severity":"critical","filePath":"system/src/Grav/Console/Gpm/DirectInstallCommand.php","lineNumber":315,"sourceCode":"\n    /**\n     * @param string $zip\n     * @param string $folder\n     * @return void\n     */\n    private function upgradeGrav(string $zip, string $folder): void\n    {\n        if (!is_dir($folder)) {\n            Installer::setError('Invalid source folder');\n        }\n\n        try {\n            $script = $folder . '/system/install.php';\n            /** Install $installer */\n            if ((file_exists($script) && $install = include $script) && is_callable($install)) {\n                $install($zip);\n            } else {\n                throw new RuntimeException('Uploaded archive file is not a valid Grav update package');\n            }\n        } catch (Exception $e) {\n            Installer::setError($e->getMessage());\n        }\n    }\n}\n","sourceCodeStart":297,"sourceCodeEnd":322,"githubUrl":"https://github.com/getgrav/grav/blob/6040efed04efa69b8209448ed81308e7c24147c2/system/src/Grav/Console/Gpm/DirectInstallCommand.php#L297-L322","documentation":"DirectInstallCommand::upgradeGrav() validates that the extracted archive is a genuine Grav core update package: it must contain system/install.php which, when included, returns a callable that performs the install. If that file is absent or does not return a callable, the archive is rejected with this RuntimeException (whose message is then stored via Installer::setError).","triggerScenarios":"Running `bin/gpm direct-install package.zip` with a GitHub 'Source code (zip)' auto-generated archive (no system/install.php), a plugin or theme zip instead of a core Grav package, a manually repacked/filtered zip that dropped system/install.php, or a truncated/corrupted download that extracted incompletely.","commonSituations":"Trying to update Grav from a GitHub release tag instead of the official getgrav.org package; feeding a locally built artifact into direct-install; downloading over a flaky connection so the zip is cut short; using direct-install on a zip that only contains the grav/ subfolder rather than the package root layout.","solutions":["Use the official package: download from getgrav.org/download (e.g. grav-v1.7.x.zip) and run `bin/gpm direct-install grav-v1.7.x.zip`.","Verify the archive layout before installing: `unzip -l package.zip | grep 'system/install.php'` — it must sit at the package root.","Re-download the package if the zip is truncated (compare size/checksum) and retry.","If you must install from source, replicate the packaging so system/install.php returning a closure is included at the root."],"exampleFix":"# before\n$ unzip -l grav-source-tag.zip   # no system/install.php -> error\n$ bin/gpm direct-install grav-source-tag.zip\n\n# after\n$ wget https://getgrav.org/download/core/grav/1.7.46 -O grav-upgrade.zip\n$ unzip -l grav-upgrade.zip   # contains system/install.php\n$ bin/gpm direct-install grav-upgrade.zip","handlingStrategy":"validation","validationCode":"// validate the archive before direct-install\n$zip = new \\ZipArchive();\nif ($zip->open($path) !== true || $zip->locateName('system/install.php') === false) {\n    exit('Not a valid Grav update package (missing system/install.php); download from getgrav.org' . PHP_EOL);\n}\n$zip->close();\n// proceed: passthru('php bin/gpm direct-install ' . escapeshellarg($path));","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Only feed `bin/gpm direct-install` packages obtained from getgrav.org/download.","Pre-check every archive with `unzip -l pkg.zip | grep system/install.php`.","Pin and checksum downloads so truncated files are caught before they reach GPM."],"tags":["grav","gpm","direct-install","upgrade","package-validation"],"backgroundTag":"invalid-upgrade-package","analyzedSha":"6040efed04efa69b8209448ed81308e7c24147c2","analyzedAt":"2026-08-17T05:07:31.593Z","schemaVersion":2},"datasetVersion":"2026-08-17T09:17:11.063Z"}