passbolt/passbolt_api · error · Cake\Http\Exception\InternalErrorException

This OpenPGP backend is not supported (rethrown backend…

Error message

This OpenPGP backend is not supported (rethrown backend failure: original exception message)

What it means

OpenPGPBackendFactory::create() instantiates the configured OpenPGP backend. When backend is GNUPG, `new Gnupg()` can itself throw a CakeException (gnupg PHP extension failure), which create() rethrows as an InternalErrorException whose message is the original exception message but prefixed in consumers with 'This OpenPGP backend is not supported' via the wrapper. Effectively: backend construction failed at runtime.

Solutions

Install/verify the extension: `php -m | grep gnupg` and `pecl install gnupg` if absent.
Ensure the GnuPG keyring directory exists and is writable by the PHP user (e.g. /var/lib/passbolt/.gnupg, correct ownership).
Check that gpg/gpg2 binaries are installed and compatible with the extension.
Read the wrapped original exception message in the trace — it names the underlying gnupg failure.

Example fix

// before: extension missing
PHP Warning: PHP Startup: Unable to load dynamic library 'gnupg.so'
// after
apt-get install gnupg libgpgme-dev && pecl install gnupg && echo 'extension=gnupg.so' > /etc/php/8.x/mods-available/gnupg.ini

Defensive patterns

Strategy: try-catch

Validate before calling

if (!extension_loaded('gnupg')) {
    throw new \RuntimeException('The PHP gnupg extension is required but not loaded.');
}

Try / catch

try {
    $backend = OpenPGPBackendFactory::get();
} catch (\Cake\Http\Exception\InternalErrorException $e) {
    if (str_contains($e->getMessage(), 'backend')) {
        // inspect $e->getPrevious() for the real gnupg failure
    }
    throw $e;
}

Prevention

Assert `extension_loaded('gnupg')` in application bootstrap/CI images.
Verify GNUPGHOME is writable by the PHP user before first request (healthcheck).
Pin the gnupg extension and libgpgme versions in your deployment image.

When it happens

Trigger: create('gnupg') is called and `new Gnupg()` throws — typically the gnupg PECL extension is installed but gnupg_init/keyring init fails, or the exception message from the constructor is propagated through InternalErrorException.

Common situations: Missing/incompatible gnupg PHP extension version; GnuPG home directory (GNUPGHOME) not writable by www-data; gpg binary missing or wrong version; extension compiled against a different libgpgme.

Related errors

AI-assisted analysis of passbolt/passbolt_api@31c1bbc10f (2026-09-17). Data as JSON: /api/errors/d51a23c5d788902d. Report an issue: GitHub.

Appendix: source

Thrown at src/Utility/OpenPGP/OpenPGPBackendFactory.php:48

     * @var \App\Utility\OpenPGP\Backends\Gnupg|null
     */
    private static ?Gnupg $instance = null;

    /**
     * Instantiate an OpenPGP Backend
     *
     * @param string $backend one of the supported backend
     * @throws \Cake\Http\Exception\InternalErrorException if backend if not supported
     * @return \App\Utility\OpenPGP\Backends\Gnupg
     */
    public static function create(string $backend = self::GNUPG): OpenPGPBackend
    {
        switch ($backend) {
            case self::GNUPG:
                try {
                    return new Gnupg();
                } catch (CakeException $exception) {
                    throw new InternalErrorException($exception->getMessage(), 500, $exception);
                }
                // no break
            default:
                throw new InternalErrorException('This OpenPGP backend is not supported');
        }
    }

    /**
     * Get a OpenPGP backend (Singleton pattern)
     *
     * @return \App\Utility\OpenPGP\OpenPGPBackend
     * @throws \Cake\Http\Exception\InternalErrorException if backend if not supported
     */
    public static function get(): OpenPGPBackend
    {
        if (self::$instance !== null) {
            return self::$instance;
        }

View on GitHub (pinned to 31c1bbc10f)