{"record":{"id":"b08a7d08cc3308e1","repo":"passbolt/passbolt_api","slug":"could-not-validate-the-settings","errorCode":null,"errorMessage":"Could not validate the settings.","messagePattern":"Could not validate the settings\\.","errorType":"validation","errorClass":"FormValidationException","httpStatus":400,"severity":"error","filePath":"plugins/PassboltCe/Metadata/src/Service/MetadataKeysSettingsAssertService.php","lineNumber":38,"sourceCode":"use Passbolt\\Metadata\\Form\\MetadataKeysSettingsForm;\nuse Passbolt\\Metadata\\Model\\Dto\\MetadataKeysSettingsDto;\n\nclass MetadataKeysSettingsAssertService\n{\n    /**\n     * Validates the setting and return them\n     *\n     * @param array $data untrusted input\n     * @param bool $validateWithMetadataPrivateKeys flag to know if metadata private key validation should be performed\n     * @return \\Passbolt\\Metadata\\Model\\Dto\\MetadataKeysSettingsDto dto\n     * @throws \\App\\Error\\Exception\\FormValidationException if the data does not validate\n     */\n    public function assert(array $data, bool $validateWithMetadataPrivateKeys = false): MetadataKeysSettingsDto\n    {\n        $form = new MetadataKeysSettingsForm();\n        $validate = $validateWithMetadataPrivateKeys ? 'withMetadataPrivateKeys' : 'default';\n        if (!$form->execute($data, compact('validate'))) {\n            throw new FormValidationException(__('Could not validate the settings.'), $form);\n        }\n\n        // TODO build rules\n        // if ZERO_KNOWLEDGE_KEY_SHARE && metadata private key exist in settings\n        //  then metadata private key must be available for the server\n\n        return new MetadataKeysSettingsDto($form->getData());\n    }\n}\n","sourceCodeStart":20,"sourceCodeEnd":48,"githubUrl":"https://github.com/passbolt/passbolt_api/blob/31c1bbc10f32808a607fa9bd81891e898779c0bc/plugins/PassboltCe/Metadata/src/Service/MetadataKeysSettingsAssertService.php#L20-L48","documentation":"MetadataKeysSettingsAssertService::assert throws FormValidationException when the provided settings data fails MetadataKeysSettingsForm validation (schema 'default' or 'withMetadataPrivateKeys'). The settings payload does not match the expected structure/values for metadata keys organization settings (e.g. zero_knowledge_key_share not boolean, unknown fields, missing metadata_private_keys when required).","triggerScenarios":"POST/PATCH to the metadata keys settings endpoint (or saveSettings calling assert) with invalid data: non-boolean zero_knowledge_key_share, missing metadata_private_keys entries when disabling zero-knowledge mode, or malformed fields; also surfaced by tests testMetadataKeysSettingsAssertService_Success/ErrorFormat.","commonSituations":"API clients sending camelCase or wrongly-named keys; omitting metadata_private_keys while switching from zero-knowledge to user-friendly mode; older client versions posting a settings shape the form no longer accepts.","solutions":["Call the form's getErrors() (included in the FormValidationException) and fix each reported field before retrying","When disabling zero-knowledge key share, include a valid metadata_private_keys array in the payload","Send exactly the documented settings fields with correct types (booleans as booleans)","Check the client/plugin version matches the server (4.10+) so the settings schema aligns"],"exampleFix":"// before\nPOST /metadata/keys/settings {\"zero_knowledge_key_share\": \"yes\"}\n// after\nPOST /metadata/keys/settings {\"zero_knowledge_key_share\": true, \"metadata_private_keys\": []}","handlingStrategy":"validation","validationCode":"$allowed = ['zero_knowledge_key_share', 'metadata_private_keys', 'allow_usage_of_personal_keys'];\n$data = array_intersect_key($data, array_flip($allowed));\nif (isset($data['zero_knowledge_key_share']) && !is_bool($data['zero_knowledge_key_share'])) {\n    throw new \\InvalidArgumentException('zero_knowledge_key_share must be boolean');\n}\n$settings = (new MetadataKeysSettingsAssertService())->assert($data); // dry-run before save","typeGuard":"function isBoolOrNull(mixed $v): bool { return $v === null || is_bool($v); }","tryCatchPattern":"try {\n    (new MetadataKeysSettingsAssertService())->assert($data);\n} catch (FormValidationException $e) {\n    $errors = $e->getForm()->getErrors(); // fix these fields then retry\n}","preventionTips":["Send exactly the documented field names and types (booleans as booleans, not strings)","When disabling zero-knowledge mode, always include metadata_private_keys","Dry-run assert() before persisting in scripts/CI that touch org settings","Keep API clients updated to match the server's settings schema"],"tags":["settings","form-validation","metadata-keys","api"],"backgroundTag":"schema-validation-failed","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"}