{"record":{"id":"af81bae72af51769","repo":"passbolt/passbolt_api","slug":"the-config-for-the-server-private-key-passphrase-is-invalid-af81ba","errorCode":null,"errorMessage":"The config for the server private key passphrase is invalid.","messagePattern":"The config for the server private key passphrase is invalid\\.","errorType":"http","errorClass":"InternalErrorException","httpStatus":500,"severity":"error","filePath":"src/Service/OpenPGP/OpenPGPCommonServerOperationsTrait.php","lineNumber":176,"sourceCode":"     */\n    private function assertServerFingerprint(mixed $fingerprint): void\n    {\n        if (!is_string($fingerprint) || !PublicKeyValidationService::isValidFingerprint($fingerprint)) {\n            $msg = __('The config for the server private key fingerprint is not available or incomplete.');\n            throw new InternalErrorException($msg);\n        }\n    }\n\n    /**\n     * @param mixed $passphrase passphrase\n     * @return void\n     * @throws \\Cake\\Http\\Exception\\InternalErrorException if the server key passphrase cannot be loaded\n     */\n    private function assertServerPassphrase(mixed $passphrase): void\n    {\n        if (!is_string($passphrase)) {\n            $msg = __('The config for the server private key passphrase is invalid.');\n            throw new InternalErrorException($msg);\n        }\n    }\n}\n","sourceCodeStart":158,"sourceCodeEnd":180,"githubUrl":"https://github.com/passbolt/passbolt_api/blob/31c1bbc10f32808a607fa9bd81891e898779c0bc/src/Service/OpenPGP/OpenPGPCommonServerOperationsTrait.php#L158-L180","documentation":"Passbolt loads the server GPG key passphrase from the Configure key `passbolt.gpg.serverKey.passphrase` before using the server key to encrypt, decrypt, verify or sign. assertServerPassphrase() requires this value to be a PHP string; if it is missing, null, an integer, or any other non-string type, an InternalErrorException (HTTP 500) is thrown. This is a server-side configuration error, not a user input problem.","triggerScenarios":"Calling setEncryptKeyWithServerKey, setDecryptKeyWithServerKey, setVerifyKeyWithServerKey or setSignKeyWithServerKey while Configure::read('passbolt.gpg.serverKey.passphrase') returns a non-string value (typically null because the config key is absent, e.g. config/app.php or environment variable PASSBOLT_GPG_SERVERKEY_PASSPHRASE not set).","commonSituations":"Fresh passbolt install where the server key passphrase entry was removed from config; Docker/Kubernetes deployments where the env var is not injected or set to an empty value that gets cast; passing an integer passphrase (e.g. a purely numeric passphrase quoted in one config file but not another); config cache stale after changing app.php.","solutions":["Define the passphrase as a string in config: Configure::write('passbolt.gpg.serverKey.passphrase', 'your-passphrase'), or in app.php under 'passbolt' => 'gpg' => 'serverKey' => 'passphrase'.","If the passphrase comes from an environment variable, ensure it is exported in the container/webserver (e.g. PASSBOLT_GPG_SERVERKEY_PASSPHRASE) and loaded via env()->read before Configure is populated.","If the server key has no passphrase, explicitly set the config to an empty string '' rather than leaving the key unset.","Clear the config/cache after editing (bin/cake cache clear_all) and restart PHP-FPM/webserver so the new Configure value is read.","Run bin/cake passbolt healthcheck to confirm the server key fingerprint and passphrase configuration are detected correctly."],"exampleFix":"// before (app.php)\n'passbolt' => [\n    'gpg' => [\n        'serverKey' => [\n            'fingerprint' => '<FINGERPRINT>',\n            // passphrase key missing -> null -> InternalErrorException\n        ],\n    ],\n],\n// after\n'passbolt' => [\n    'gpg' => [\n        'serverKey' => [\n            'fingerprint' => '<FINGERPRINT>',\n            'passphrase' => 'my-secret-passphrase', // string, use '' if key is unprotected\n        ],\n    ],\n],","handlingStrategy":"validation","validationCode":"$passphrase = Configure::read('passbolt.gpg.serverKey.passphrase');\nif (!is_string($passphrase)) {\n    throw new RuntimeException(\n        'passbolt.gpg.serverKey.passphrase must be a string, got: '\n        . get_debug_type($passphrase)\n    );\n}","typeGuard":"function isServerKeyPassphraseSet(mixed $value): bool\n{\n    return is_string($value);\n}","tryCatchPattern":"try {\n    $gpg = $this->setEncryptKeyWithServerKey($gpg);\n} catch (InternalErrorException $e) {\n    if (str_contains($e->getMessage(), 'passphrase')) {\n        // config problem: fail fast with actionable message\n        throw new RuntimeException('Server key passphrase not configured as a string.', 0, $e);\n    }\n    throw $e;\n}","preventionTips":["Always define passbolt.gpg.serverKey.passphrase in config/app.php or via env var, even as an empty string for unprotected keys.","Quote numeric or special-character passphrases so YAML/PHP parsing yields a string, not int.","Add a deployment healthcheck asserting Configure::read('passbolt.gpg.serverKey.passphrase') is a string before booting features that use the server key.","Clear config cache and restart the webserver after changing GPG config.","Run bin/cake passbolt healthcheck after every deploy to catch server key config regressions."],"tags":["openpgp","configuration","gpg","server-key","passphrase"],"backgroundTag":"invalid-config-value","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"}