What causes "The key {0} was not found in the keyring" in passbolt/passbolt_api?

Import the missing key into the keyring (e.g. `gpg --home --import key.asc`) or re-run passbolt's key import command.

passbolt/passbolt_api · error · Cake\Core\Exception\CakeException

The key was not found in the keyring

Error message

The key {0} was not found in the keyring

What it means

OpenPGPCommonAssertsTrait::assertKeyInKeyring() is a guard method that verifies a given fingerprint exists in the GnuPG keyring before performing key operations. It throws a CakeException when isKeyInKeyring() reports the fingerprint is absent, stopping operations that would otherwise fail later inside GnuPG with less clear errors.

Solutions

Import the missing key into the keyring (e.g. `gpg --home <GNUPGHOME> --import key.asc`) or re-run passbolt's key import command.
Verify the fingerprint string matches exactly (40 hex chars, no stray whitespace) what `gpg --fingerprint` shows.
Check the GNUPGHOME environment/config points to the keyring that actually contains the key and is readable by the PHP process user.
If the key was rotated, update the application configuration to reference the new fingerprint.

Example fix

// before
$gpg->assertKeyInKeyring($fingerprint); // throws if not imported
// after
if (!$gpg->isKeyInKeyring($fingerprint)) {
    $gpg->importKeyIntoKeyring(file_get_contents($keyPath));
}
$gpg->assertKeyInKeyring($fingerprint);

Defensive patterns

Strategy: validation

Validate before calling

if (!preg_match('/^[0-9A-F]{40}$/i', $fingerprint) || !$gpg->isKeyInKeyring($fingerprint)) {
    $gpg->importKeyIntoKeyring($keyData); // or skip with a clear message
}

Type guard

function keyExistsInKeyring($gpg, string $fingerprint): bool {
    return is_string($fingerprint) && preg_match('/^[0-9A-F]{40}$/i', $fingerprint) === 1
        && $gpg->isKeyInKeyring($fingerprint);
}

Try / catch

try {
    $gpg->assertKeyInKeyring($fingerprint);
} catch (\Cake\Core\Exception\CakeException $e) {
    // key missing: import it or report a 4xx-style configuration problem
    $this->importMissingKey($fingerprint);
}

Prevention

Import all required keys (server key, user keys) as part of deployment/setup scripts.
Normalize fingerprints (strip spaces, uppercase) before use.
Point GNUPGHOME consistently in config and make it readable by the PHP user.
Add a health check that verifies configured fingerprints exist in the keyring at startup.

When it happens

Trigger: Calling assertKeyInKeyring($fingerprint) with a fingerprint that is not imported into the keyring of the configured GNUPGHOME — e.g. verifying or decrypting with a recipient/sender key that was never imported, or a fingerprint with wrong casing/spaces.

Common situations: Missing public key import during setup or deployment (fresh container with empty GNUPGHOME), server key rotation where the old key was deleted, typo in fingerprint config, tests running as a user without the keyring, or keyring path misconfiguration pointing at an empty directory.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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

Appendix: source

Thrown at src/Utility/OpenPGP/Traits/OpenPGPCommonAssertsTrait.php:55

            throw new CakeException($msg);
        }
        if ($m !== $marker) {
            throw new CakeException($msg);
        }

        return true;
    }

    /**
     * Assert key is in the keyring
     *
     * @param string $fingerprint fingerprint
     * @return void
     */
    public function assertKeyInKeyring(string $fingerprint): void
    {
        if (!$this->isKeyInKeyring($fingerprint)) {
            throw new CakeException(__('The key {0} was not found in the keyring', $fingerprint));
        }
    }

    /**
     * Assert the signature key is set
     *
     * @throws \Cake\Core\Exception\CakeException if not signature key is set
     * @return void
     */
    public function assertSignKey(): void
    {
        if (empty($this->_signKeyFingerprint)) {
            throw new CakeException('Can not sign without a key. Set a sign key first.');
        }
    }

    /**
     * Assert the verification key is set

View on GitHub (pinned to 31c1bbc10f)