passbolt/passbolt_api · error · FormValidationException

Could not validate the settings.

Error message

Could not validate the settings.

What it means

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).

Solutions

1. Call the form's getErrors() (included in the FormValidationException) and fix each reported field before retrying
2. When disabling zero-knowledge key share, include a valid metadata_private_keys array in the payload
3. Send exactly the documented settings fields with correct types (booleans as booleans)
4. Check the client/plugin version matches the server (4.10+) so the settings schema aligns

Example fix

// before
POST /metadata/keys/settings {"zero_knowledge_key_share": "yes"}
// after
POST /metadata/keys/settings {"zero_knowledge_key_share": true, "metadata_private_keys": []}

$allowed = ['zero_knowledge_key_share', 'metadata_private_keys', 'allow_usage_of_personal_keys'];
$data = array_intersect_key($data, array_flip($allowed));
if (isset($data['zero_knowledge_key_share']) && !is_bool($data['zero_knowledge_key_share'])) {
    throw new \InvalidArgumentException('zero_knowledge_key_share must be boolean');
}
$settings = (new MetadataKeysSettingsAssertService())->assert($data); // dry-run before save

function isBoolOrNull(mixed $v): bool { return $v === null || is_bool($v); }

try {
    (new MetadataKeysSettingsAssertService())->assert($data);
} catch (FormValidationException $e) {
    $errors = $e->getForm()->getErrors(); // fix these fields then retry
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Could not validate the metadata key data.
• Could not validate the metadata key data.
• Could not validate the password policies settings.
• Could not validate the settings.
• The supplied email notification settings are not valid

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

Appendix: source

Thrown at plugins/PassboltCe/Metadata/src/Service/MetadataKeysSettingsAssertService.php:38

use Passbolt\Metadata\Form\MetadataKeysSettingsForm;
use Passbolt\Metadata\Model\Dto\MetadataKeysSettingsDto;

class MetadataKeysSettingsAssertService
{
    /**
     * Validates the setting and return them
     *
     * @param array $data untrusted input
     * @param bool $validateWithMetadataPrivateKeys flag to know if metadata private key validation should be performed
     * @return \Passbolt\Metadata\Model\Dto\MetadataKeysSettingsDto dto
     * @throws \App\Error\Exception\FormValidationException if the data does not validate
     */
    public function assert(array $data, bool $validateWithMetadataPrivateKeys = false): MetadataKeysSettingsDto
    {
        $form = new MetadataKeysSettingsForm();
        $validate = $validateWithMetadataPrivateKeys ? 'withMetadataPrivateKeys' : 'default';
        if (!$form->execute($data, compact('validate'))) {
            throw new FormValidationException(__('Could not validate the settings.'), $form);
        }

        // TODO build rules
        // if ZERO_KNOWLEDGE_KEY_SHARE && metadata private key exist in settings
        //  then metadata private key must be available for the server

        return new MetadataKeysSettingsDto($form->getData());
    }
}

View on GitHub (pinned to 31c1bbc10f)