passbolt/passbolt_api · error · BadRequestException

V4 related fields are not supported for V5.

Error message

V4 related fields are not supported for V5.

What it means

MetadataFolderDto's validate() rejects folder creation/update payloads that mix v5 metadata fields (metadata, metadata_key_id, metadata_key_type) with v4 cleartext fields (name). Once any v5 field is present the payload is treated as v5, and any non-null v4 field triggers this BadRequestException. Passbolt throws it to enforce strict separation between the legacy v4 cleartext format and the encrypted v5 metadata format.

Solutions

1. Remove the v4 fields (`name` for folders) from the request payload and send only the v5 fields: metadata, metadata_key_id, metadata_key_type.
2. Decide the format version explicitly: for v4 send only `name` (no metadata fields), for v5 send only encrypted metadata fields.
3. Update the calling client/SDK to target the server's metadata (v5) format, e.g. by encrypting name into `metadata` with OpenPGP before the call.
4. If v5 is not intended, disable the Passbolt/Metadata plugin so the DTO nulls the v5 fields and accepts v4 payloads.

Example fix

// before
POST /folders.json
{"name": "My folder", "metadata": "<encrypted>", "metadata_key_id": "<uuid>", "metadata_key_type": "shared_key"}

// after
POST /folders.json
{"metadata": "<encrypted>", "metadata_key_id": "<uuid>", "metadata_key_type": "shared_key"}

// PHP (caller side)
$v5 = ['metadata', 'metadata_key_id', 'metadata_key_type'];
$isV5 = count(array_filter($payload, fn($v, $k) => in_array($k, $v5, true) && $v !== null, ARRAY_FILTER_USE_BOTH)) > 0;
if ($isV5 && isset($payload['name']) && $payload['name'] !== null) {
    unset($payload['name']); // v4 field not allowed with v5
}

function isPureV5FolderPayload(array $p): bool {
    $hasV5 = (isset($p['metadata']) && $p['metadata'] !== null);
    $hasV4 = (isset($p['name']) && $p['name'] !== null);
    return $hasV5 && !$hasV4;
}

try {
    $dto = MetadataFolderDto::fromArray($payload);
} catch (BadRequestException $e) {
    // 400: strip v4 'name' and retry with pure v5 payload, or log and abort
}

When it happens

Trigger: POST/PUT to the folders endpoints (e.g. /folders.json or /folders/<id>.json) with body containing both `name` and any of `metadata`/`metadata_key_id`/`metadata_key_type` (all non-null), while the Metadata plugin is enabled; constructing MetadataFolderDto::fromArray with such mixed data.

Common situations: Migrating clients from v4 to v5 that keep sending the legacy `name` field alongside encrypted metadata; scripts or integrations built for passbolt <=4.x hitting a v5-enabled server; partially updated SDK/API wrappers that merged the two payload formats.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

• V4 related fields are not supported for V5.
• Few fields are missing for the V5.
• The metadata private key data must be an array.
• An array of arrays is expected.
• The entity must be an array.

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

Appendix: source

Thrown at plugins/PassboltCe/Metadata/src/Model/Dto/MetadataFolderDto.php:187

            throw new BadRequestException($msg);
        }

        // Now that we know that we have a valid v5 payload, we check that no v4 fields are in the payload
        $v4SuperfluousFields = [];
        foreach (self::V4_META_PROPS as $v4Field) {
            if (array_key_exists($v4Field, $data) && !is_null($data[$v4Field])) {
                $v4SuperfluousFields[] = $v4Field;
            }
        }
        if (!empty($v4SuperfluousFields)) {
            $msg = __('V4 related fields are not supported for V5.');
            if (Configure::read('debug')) {
                Log::error($msg);
                Log::error(__('Superfluous fields: {0}', implode(', ', $v4SuperfluousFields)));
            }

            throw new BadRequestException($msg);
        }
    }

    /**
     * Returns metadata array in cleartext form as per v5 format.
     *
     * @return array
     */
    public function getClearTextMetadata(): array
    {
        return [
            'object_type' => 'PASSBOLT_FOLDER_METADATA',
            'name' => $this->name,
            // below fields are null for now will be added in future
            'color' => null,
            'description' => null,
            'icon' => null,
        ];

View on GitHub (pinned to 31c1bbc10f)