passbolt/passbolt_api · critical · InternalErrorException

The config for the server private key fingerprint is not…

Error message

The config for the server private key fingerprint is not available or incomplete.

What it means

Thrown by assertServerFingerprint (invoked by all four set*KeyWithServerKey methods) when passbolt.gpg.serverKey.fingerprint is missing from Configure, is not a string, or fails PublicKeyValidationService::isValidFingerprint (wrong length/charset). It is a fail-fast config assertion before any GnuPG operation is attempted, so no underlying gnupg message is attached.

Solutions

1. Generate or locate the server key fingerprint: `gpg --show-keys /etc/passbolt/serverkey.asc` (or run the passbolt key-generation command on first install).
2. Set a valid 40-character uppercase hex fingerprint under passbolt.gpg.serverKey.fingerprint in config/app.php or passbolt.php.
3. If the value comes from an environment variable, verify it is actually set in the container/service environment (`printenv | grep -i fingerprint`).
4. Confirm the config file is being loaded (check passbolt.php include/merge and that Configure::read('passbolt.gpg.serverKey.fingerprint') returns the value, e.g. via a healthcheck command).
5. Normalize the value: strip whitespace/newlines and uppercase it so isValidFingerprint passes.

Example fix

// before (config/app.php)
'serverKey' => [
    'fingerprint' => env('PASSBOLT_SERVERKEY_FINGERPRINT'), // env var unset → null
],
// after
'serverKey' => [
    'fingerprint' => '52729A1CB5D8B6C4F3C0A1B2D4E5F60718293A4B', // 40 uppercase hex chars
],

use App\Service\OpenPGP\PublicKeyValidationService;
use Cake\Core\Configure;

$fingerprint = Configure::read('passbolt.gpg.serverKey.fingerprint');
if (!is_string($fingerprint) || !PublicKeyValidationService::isValidFingerprint($fingerprint)) {
    throw new Exception('passbolt.gpg.serverKey.fingerprint is not set or is not a valid 40-char hex fingerprint');
}

function isValidFingerprintConfig(mixed $fingerprint): bool
{
    return is_string($fingerprint)
        && PublicKeyValidationService::isValidFingerprint($fingerprint);
}

try {
    $gpg = $this->setEncryptKeyWithServerKey($gpg);
} catch (InternalErrorException $e) {
    if (str_contains($e->getMessage(), 'fingerprint is not available or incomplete')) {
        Log::error('passbolt.gpg.serverKey.fingerprint missing/invalid in config');
    }
    throw $e;
}

When it happens

Trigger: passbolt.gpg.serverKey.fingerprint absent from config (config/app.php or passbolt.php not loaded/merged); value set to null/false/empty string; fingerprint containing lowercase letters, spaces, or fewer/more than 40 hex characters; environment variable interpolation producing an empty value (e.g. missing PASSBOLT_SERVERKEY_FINGERPRINT env var); config file loaded but the key was renamed.

Common situations: Fresh install where `passbolt install` was never run and no server key was generated; hand-edited config dropping the fingerprint key; Docker deployments where the env var holding the fingerprint is unset; switching between config files (default.php/app.php) and losing the override; typos like a 39-character fingerprint after copy/paste.

Understand the failure class

Background: "missing required config value" errors: why libraries refuse to start when a configuration key is empty, unset, or blank — this error's family across 48 libraries.

Related errors

• Invalid fingerprint.
• Invalid request, message validation rules are missing.
• A valid OpenPGP key must be provided.
• A valid OpenPGP key must be provided.
• A value for the theme should be provided.

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

Appendix: source

Thrown at src/Service/OpenPGP/OpenPGPCommonServerOperationsTrait.php:163

                $msg = __('The OpenPGP server key defined in the config cannot be used to sign.') . ' ';
                $msg .= $exception->getMessage();
                throw new InternalErrorException($msg, 500, $exception);
            }
        }

        return $gpg;
    }

    /**
     * @param mixed $fingerprint fingerprint
     * @return void
     * @throws \Cake\Http\Exception\InternalErrorException if the server key fingerprint cannot be loaded
     */
    private function assertServerFingerprint(mixed $fingerprint): void
    {
        if (!is_string($fingerprint) || !PublicKeyValidationService::isValidFingerprint($fingerprint)) {
            $msg = __('The config for the server private key fingerprint is not available or incomplete.');
            throw new InternalErrorException($msg);
        }
    }

    /**
     * @param mixed $passphrase passphrase
     * @return void
     * @throws \Cake\Http\Exception\InternalErrorException if the server key passphrase cannot be loaded
     */
    private function assertServerPassphrase(mixed $passphrase): void
    {
        if (!is_string($passphrase)) {
            $msg = __('The config for the server private key passphrase is invalid.');
            throw new InternalErrorException($msg);
        }
    }
}

View on GitHub (pinned to 31c1bbc10f)