passbolt/passbolt_api · error · BadRequestException

The metadata key ID should be a valid UUID.

Error message

The metadata key ID should be a valid UUID.

What it means

Format guard in the metadata key delete action: the id route parameter fails Validation::uuid(), so the metadata key identifier is malformed and the delete is rejected with 400 before the key is looked up.

Solutions

1. Send the metadata key's UUID as the path parameter.
2. Look up the correct key id first via GET /metadata/keys and use the 'id' field.
3. Fix URL construction in the client; validate the id is a UUID before calling.

Example fix

// before
fetch(`/metadata/keys/${key.fingerprint}`, {method:'DELETE'});
// after
fetch(`/metadata/keys/${key.id}`, {method:'DELETE'});

const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
if (!UUID_RE.test(id)) throw new Error('metadata key id must be a UUID');

const isUuid = (v) => typeof v === 'string' && /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(v);

try { await api.del(`/metadata/keys/${id}`); } catch (e) { if (e.response?.status === 400) { id = await resolveKeyIdFromApi(); retry(); } else throw e; }

When it happens

Trigger: DELETE request to /metadata/keys/{id} where {id} is not a valid UUID (e.g. a fingerprint, slug, numeric id, or truncated string).

Common situations: Clients storing key fingerprints instead of the metadata key UUID; hand-built URLs; typos when copying an id; older v4 resource-key identifiers used against the v5 endpoint.

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

Related errors

• The metadata key ID should be a valid UUID.
• The metadata key identifier should be a UUID.
• The private key identifier should be a UUID.
• Invalid id
• Invalid request. New key or passwords are not required.

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

Appendix: source

Thrown at plugins/PassboltCe/Metadata/src/Controller/MetadataKeyDeleteController.php:40

use Passbolt\Metadata\Service\MetadataKey\MetadataKeyDeleteService;

class MetadataKeyDeleteController extends AppController
{
    /**
     * Delete a given metadata key
     *
     * @param string $id key uuid
     * @return void
     * @throws \Cake\Http\Exception\NotFoundException if the key does not exist or is already deleted
     * @throws \Cake\Http\Exception\BadRequestException if the key id format is Invalid or some items are still using the key
     * @throws \Cake\Http\Exception\InternalErrorException if there was an issue during the save/delete
     */
    public function delete(string $id): void
    {
        $this->assertJson();
        $this->User->assertIsAdmin();
        if (!Validation::uuid($id)) {
            throw new BadRequestException(__('The metadata key ID should be a valid UUID.'));
        }

        (new MetadataKeyDeleteService())->delete($this->User->getAccessControl(), $id);
        $this->success(__('The operation was successful.'));
    }
}

View on GitHub (pinned to 31c1bbc10f)