{"record":{"id":"ae44fa68273033f7","repo":"passbolt/passbolt_api","slug":"php-gnupg-library-is-not-installed","errorCode":null,"errorMessage":"PHP Gnupg library is not installed.","messagePattern":"PHP Gnupg library is not installed\\.","errorType":"exception","errorClass":"CakeException","httpStatus":500,"severity":"critical","filePath":"src/Utility/OpenPGP/Backends/Gnupg.php","lineNumber":59,"sourceCode":"class Gnupg extends OpenPGPBackend\n{\n    /**\n     * Gpg object.\n     *\n     * @var \\gnupg\n     */\n    protected PhpGnupg $_gpg;\n\n    /**\n     * Constructor.\n     *\n     * @throws \\Cake\\Core\\Exception\\CakeException\n     */\n    public function __construct()\n    {\n        parent::__construct();\n        if (!extension_loaded('gnupg')) {\n            throw new CakeException('PHP Gnupg library is not installed.');\n        }\n        if (Configure::read('passbolt.gpg.putenv')) {\n            putenv('GNUPGHOME=' . Configure::read('passbolt.gpg.keyring'));\n        }\n\n        $this->_gpg = new PhpGnupg();\n        $this->_gpg->seterrormode(GNUPG_ERROR_EXCEPTION);\n    }\n\n    /**\n     * Set a key for encryption.\n     *\n     * @param string $armoredKey ASCII armored key data\n     * @throws \\Cake\\Core\\Exception\\CakeException if the key cannot be used to encrypt\n     * @return bool true if success\n     */\n    public function setEncryptKey(string $armoredKey): bool\n    {","sourceCodeStart":41,"sourceCodeEnd":77,"githubUrl":"https://github.com/passbolt/passbolt_api/blob/31c1bbc10f32808a607fa9bd81891e898779c0bc/src/Utility/OpenPGP/Backends/Gnupg.php#L41-L77","documentation":"The Gnupg OpenPGP backend requires the PHP gnupg extension (a wrapper around libgpgme). Its constructor calls extension_loaded('gnupg') and throws a CakeException immediately if the extension is absent, before any keyring operations can run. This is an environment/setup failure, not a data problem: the passbolt container or server was built without the extension or it was not enabled in the SAPI.","triggerScenarios":"Instantiating App\\Utility\\OpenPGP\\Backends\\Gnupg (directly or via OpenPGPBackend factory) on a PHP build where the gnupg extension is not compiled/loaded, e.g. stock php without php-gnupg installed, or the extension exists on CLI but not in the web server SAPI (different php.ini).","commonSituations":"Deploying passbolt on a self-managed server where php-gnupg (pecl/gnupg + libgpgme-dev) was never installed; switching PHP versions (e.g. via ondrej PPA or brew) and forgetting to reinstall the extension; Docker images built from a bare php base without the extension; CLI works but fpm/apache SAPI lacks the ini entry.","solutions":["Install the extension: apt install php-gnupg (or pecl install gnupg after apt install libgpgme-dev) and restart the PHP SAPI (php-fpm/apache).","Verify with php -m | grep gnupg and, for the web SAPI, a phpinfo() page or php-fpm php.ini containing extension=gnupg.so.","If multiple PHP versions are in play, install the extension for the exact version/SAPI running passbolt (e.g. php8.2-gnupg).","Use the official passbolt Docker image or package repositories, which ship the gnupg extension preconfigured."],"exampleFix":"// before (web SAPI php.ini has no gnupg)\n; extension=gnupg.so\n// after\nextension=gnupg.so\n# then: sudo systemctl restart php8.2-fpm && php -m | grep gnupg","handlingStrategy":"type-guard","validationCode":"if (!extension_loaded('gnupg')) {\n    throw new \\RuntimeException(\n        'The PHP gnupg extension is required. Install php-gnupg and restart the SAPI.'\n    );\n}\n// also verify in the same SAPI that serves passbolt (php-fpm, not just CLI)\n","typeGuard":"function isGnupgAvailable(): bool\n{\n    return extension_loaded('gnupg') && class_exists('gnupg');\n}\n","tryCatchPattern":"try {\n    $backend = new \\App\\Utility\\OpenPGP\\Backends\\Gnupg();\n} catch (\\Cake\\Core\\Exception\\CakeException $e) {\n    // fail fast at bootstrap with a clear setup instruction\n    exit($e->getMessage() . PHP_EOL . 'Run: apt install php-gnupg && systemctl restart php-fpm');\n}\n","preventionTips":["Add php-gnupg to your deployment provisioning/infrastructure-as-code for every PHP version used.","Check php -m | grep gnupg in a pre-deploy health check for the exact SAPI.","Use official passbolt Docker images or distro packages that bundle the extension.","After any PHP upgrade, re-verify extension presence before deploying."],"tags":["php","gpg","missing-extension","environment"],"backgroundTag":"missing-dependency","analyzedSha":"31c1bbc10f32808a607fa9bd81891e898779c0bc","analyzedAt":"2026-09-17T00:04:38.960Z","contentChangedAt":"2026-09-17T00:04:38.960Z","schemaVersion":2},"datasetVersion":"2026-09-21T04:17:39.646Z"}