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 update action (used to expire keys): the id route parameter does not pass Validation::uuid(), so the metadata key identifier is invalid and the request is rejected with 400.

Solutions

1. Pass the metadata key UUID in the path.
2. Fetch GET /metadata/keys to resolve the correct UUID.
3. Add client-side UUID validation before issuing the request.

Example fix

// before
client.updateMetadataKey(fingerprint, data);
// after
if (!isUuid(fingerprint)) throw new Error('id must be a UUID');
client.updateMetadataKey(keyId /* uuid */, data);

if (!isUuid(id)) throw new Error('id must be a UUID'); await api.put(`/metadata/keys/${id}`, body);

function isUuid(v) { return 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.put(`/metadata/keys/${id}`, body); } catch (e) { if (e.response?.status === 400 && String(e.message).includes('UUID')) { throw new ProgrammerError('use the metadata key UUID, not ' + id); } throw e; }

When it happens

Trigger: Metadata key update call where {id} is not a valid UUID string.

Common situations: Using a key fingerprint or resource id instead of the metadata key UUID; empty id from a templated URL; truncated identifiers in test scripts.

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/bcd732e62f4cd937. Report an issue: GitHub.

Appendix: source

Thrown at plugins/PassboltCe/Metadata/src/Controller/MetadataKeyUpdateController.php:46

{
    /**
     * Update a given metadata key,
     * Used only to mark keys as expired
     *
     * @param string $id key uuid
     * @return void
     * @throws \Cake\Http\Exception\NotFoundException if the key does not exist or is already expired
     * @throws \Cake\Http\Exception\BadRequestException if the key format is invalid or some conditions are not met
     * @throws \Cake\Http\Exception\InternalErrorException if there was an issue during the save/delete
     */
    public function update(string $id): void
    {
        $this->assertJson();
        $this->User->assertIsAdmin();
        $this->assertNotEmptyArrayData();

        if (!Validation::uuid($id)) {
            throw new BadRequestException(__('The metadata key ID should be a valid UUID.'));
        }

        $form = new MetadataKeyUpdateForm();
        if (!$form->execute($this->getRequest()->getData())) {
            throw new FormValidationException(__('Could not validate the metadata key data.'), $form);
        }

        $dto = MetadataKeyUpdateDto::fromArray($form->getData());
        (new MetadataKeyUpdateService())->update($this->User->getAccessControl(), $id, $dto);
        $this->success(__('The operation was successful.'));
    }
}

View on GitHub (pinned to 31c1bbc10f)