passbolt/passbolt_api · error · BadRequestException

The server metadata private key is required to enable these…

Error message

The server metadata private key is required to enable these settings.

What it means

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.

Solutions

1. Include a 'metadata_private_keys' array with at least one entry (signed server key data) in the settings payload
2. If disabling personal keys is not intended, adjust the settings flags so the private-key generation path is not triggered
3. Check the client SDK version matches the server API version that requires metadata_private_keys
4. Log and inspect the exact request body to confirm the field is present, an array, and non-empty

Example fix

// before
{"metadata_keys_settings": {"allow_usage_of_personal_keys": false}}
// after
{"metadata_keys_settings": {"allow_usage_of_personal_keys": false, "metadata_private_keys": [{"data": "<armored-key>"}]}}

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'); }

function hasPrivateKeys(p) { return Array.isArray(p?.metadata_private_keys) && p.metadata_private_keys.length > 0; }

catch (e) { if (e.response?.status === 400 && /metadata private key is required/.test(e.response?.body?.message)) { fixPayloadAndRetry(); } else { throw e; } }

When it happens

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

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

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Could not validate the settings.
• Few fields are missing for the V5.
• The metadata key is already shared with the user.
• V4 related fields are not supported for V5.
• 400

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

Appendix: source

Thrown at plugins/PassboltCe/Metadata/src/Service/MetadataKeysSettingsSetService.php:111

            ->all()
            ->count();

        if ($nonDeletedKeysCount && $settingsDto->isUserFriendlyMode()) {
            /** @var \Passbolt\Metadata\Model\Table\MetadataPrivateKeysTable $metadataPrivateKeysTable */
            $metadataPrivateKeysTable = $this->fetchTable('Passbolt/Metadata.MetadataPrivateKeys');
            $serverKeysCount = $metadataPrivateKeysTable->find()
                ->where(['user_id IS' => null])
                ->orderBy(['created' => 'DESC'])
                ->all()
                ->count();
            if ($serverKeysCount === 0) {
                if (
                    !isset($data['metadata_private_keys']) ||
                    !is_array($data['metadata_private_keys']) ||
                    !count($data['metadata_private_keys'])
                ) {
                    $msg = __('The server metadata private key is required to enable these settings.');
                    throw new BadRequestException($msg);
                }

                return true;
            }
        }

        return false;
    }

    /**
     * When updating the settings, we want to know if the zero knowledge mode is being disabled.
     * If so, metadata private keys will be requested in the payload at a later stage.
     *
     * @param array $data payload
     * @param \Passbolt\Metadata\Model\Dto\MetadataKeysSettingsDto $organizationSetting DTO of the settings currently in DB
     * @return bool
     */
    private function isDisablingZeroKnowledge(array $data, MetadataKeysSettingsDto $organizationSetting): bool

View on GitHub (pinned to 31c1bbc10f)