{"record":{"id":"2130a901c5ade90f","repo":"passbolt/passbolt_api","slug":"the-server-metadata-private-key-is-required-to-enable-these","errorCode":null,"errorMessage":"The server metadata private key is required to enable these settings.","messagePattern":"The server metadata private key is required to enable these settings\\.","errorType":"http","errorClass":"BadRequestException","httpStatus":400,"severity":"error","filePath":"plugins/PassboltCe/Metadata/src/Service/MetadataKeysSettingsSetService.php","lineNumber":111,"sourceCode":"            ->all()\n            ->count();\n\n        if ($nonDeletedKeysCount && $settingsDto->isUserFriendlyMode()) {\n            /** @var \\Passbolt\\Metadata\\Model\\Table\\MetadataPrivateKeysTable $metadataPrivateKeysTable */\n            $metadataPrivateKeysTable = $this->fetchTable('Passbolt/Metadata.MetadataPrivateKeys');\n            $serverKeysCount = $metadataPrivateKeysTable->find()\n                ->where(['user_id IS' => null])\n                ->orderBy(['created' => 'DESC'])\n                ->all()\n                ->count();\n            if ($serverKeysCount === 0) {\n                if (\n                    !isset($data['metadata_private_keys']) ||\n                    !is_array($data['metadata_private_keys']) ||\n                    !count($data['metadata_private_keys'])\n                ) {\n                    $msg = __('The server metadata private key is required to enable these settings.');\n                    throw new BadRequestException($msg);\n                }\n\n                return true;\n            }\n        }\n\n        return false;\n    }\n\n    /**\n     * When updating the settings, we want to know if the zero knowledge mode is being disabled.\n     * If so, metadata private keys will be requested in the payload at a later stage.\n     *\n     * @param array $data payload\n     * @param \\Passbolt\\Metadata\\Model\\Dto\\MetadataKeysSettingsDto $organizationSetting DTO of the settings currently in DB\n     * @return bool\n     */\n    private function isDisablingZeroKnowledge(array $data, MetadataKeysSettingsDto $organizationSetting): bool","sourceCodeStart":93,"sourceCodeEnd":129,"githubUrl":"https://github.com/passbolt/passbolt_api/blob/31c1bbc10f32808a607fa9bd81891e898779c0bc/plugins/PassboltCe/Metadata/src/Service/MetadataKeysSettingsSetService.php#L93-L129","documentation":"Thrown by MetadataKeysSettingsSetService::shouldCreateMetadataPrivateKey when the admin enables metadata key settings that require generating/rotating a server metadata private key, but the request payload contains no 'metadata_private_keys' array. It is a BadRequestException signalling a malformed enable-settings request, not a server fault.","triggerScenarios":"POST/PUT to the metadata keys settings endpoint with allow_usage_of_personal_keys=false (or generate_server_key flow) while omitting metadata_private_keys, passing it as null, or passing an empty array [].","commonSituations":"Clients upgrading to the metadata server-key feature but sending the old settings payload shape; hand-built JSON missing the key; automation scripts that clear the field when disabling then re-enabling settings.","solutions":["Include a 'metadata_private_keys' array with at least one entry (signed server key data) in the settings payload","If disabling personal keys is not intended, adjust the settings flags so the private-key generation path is not triggered","Check the client SDK version matches the server API version that requires metadata_private_keys","Log and inspect the exact request body to confirm the field is present, an array, and non-empty"],"exampleFix":"// before\n{\"metadata_keys_settings\": {\"allow_usage_of_personal_keys\": false}}\n// after\n{\"metadata_keys_settings\": {\"allow_usage_of_personal_keys\": false, \"metadata_private_keys\": [{\"data\": \"<armored-key>\"}]}}","handlingStrategy":"validation","validationCode":"if (!isset(payload.metadata_private_keys) || !Array.isArray(payload.metadata_private_keys) || payload.metadata_private_keys.length === 0) { throw new Error('metadata_private_keys must be a non-empty array'); }","typeGuard":"function hasPrivateKeys(p) { return Array.isArray(p?.metadata_private_keys) && p.metadata_private_keys.length > 0; }","tryCatchPattern":"catch (e) { if (e.response?.status === 400 && /metadata private key is required/.test(e.response?.body?.message)) { fixPayloadAndRetry(); } else { throw e; } }","preventionTips":["Always build settings payloads from the server's OpenAPI/schema, not by hand","Add a client-side preflight check that enable-server-key requests include the private-key array","Pin client SDK version to the server API version"],"tags":["http-400","metadata","settings","request-payload"],"backgroundTag":"missing-required-argument","analyzedSha":"31c1bbc10f32808a607fa9bd81891e898779c0bc","analyzedAt":"2026-09-17T00:04:38.960Z","contentChangedAt":"2026-09-17T00:04:38.960Z","schemaVersion":2},"datasetVersion":"2026-09-21T09:17:21.228Z"}