passbolt/passbolt_api · error · NotFoundException

The metadata key fingerprint is invalid.

Error message

The metadata key fingerprint is invalid.

What it means

Update requires the supplied fingerprint in the DTO to exactly match the stored key's fingerprint — the update endpoint exists to amend expiry/delete data of an existing key, not to change its identity. A mismatch throws NotFoundException (HTTP 404).

Solutions

1. Send the exact fingerprint returned by GET /metadata/keys for that id (same casing, no whitespace)
2. Make sure the id and fingerprint in the request both refer to the same key
3. If intending to replace a key, use the rotation flow instead of the update endpoint

Example fix

// before
await updateMetadataKey(keyA.id, { fingerprint: keyB.fingerprint });
// after
await updateMetadataKey(keyA.id, { fingerprint: keyA.fingerprint });

const key = await getMetadataKey(id);
if (dto.fingerprint !== key.fingerprint) {
  throw new Error('fingerprint does not match key');
}

try {
  await updateMetadataKey(id, dto);
} catch (e) {
  if (e.status === 404 && /fingerprint is invalid/.test(e.message)) {
    dto.fingerprint = (await getMetadataKey(id)).fingerprint;
    return updateMetadataKey(id, dto);
  }
  throw e;
}

When it happens

Trigger: PUT /metadata/keys/<id> whose dto.fingerprint differs from the persisted key's fingerprint — e.g. caller sends the fingerprint of a different key, a normalized/uppercased variant, or an empty/placeholder value.

Common situations: Client mixes up two keys during rotation; fingerprint case or whitespace differences (passbolt fingerprints are uppercase); stale DTO built from an older key version.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• The metadata key does not exist or has been deleted.
• The metadata key does not exist or has been deleted.
• The metadata key has already been deleted.
• A value for the theme should be provided.
• AssociatedRecordExists

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

Appendix: source

Thrown at plugins/PassboltCe/Metadata/src/Service/MetadataKey/MetadataKeyUpdateService.php:67

        $uac->assertIsAdmin();

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

        $metadataKeysTable = $this->fetchTable('Passbolt/Metadata.MetadataKeys');

        // Assert the key exist
        try {
            /** @var \Passbolt\Metadata\Model\Entity\MetadataKey $metadataKey */
            $metadataKey = $metadataKeysTable->get($id);
        } catch (RecordNotFoundException $exception) { // @phpstan-ignore-line
            throw new NotFoundException(__('The metadata key does not exist or has been deleted.'), 404, $exception);
        }

        // Assert fingerprint is the same
        if ($metadataKey->fingerprint !== $dto->fingerprint) {
            throw new NotFoundException(__('The metadata key fingerprint is invalid.'));
        }

        // Assert the key is not already deleted
        if ($metadataKey->isDeleted()) {
            throw new NotFoundException(__('The metadata key has already been deleted.'));
        }

        // Assert they key was not previously marked as expired
        if ($metadataKey->isExpired()) {
            throw new BadRequestException(__('The metadata key is already marked as expired.'));
        }

        // Patch the key deleted field with the current time
        $options = [
            'accessibleFields' => [
                'fingerprint' => true, 'armored_key' => true, 'expired' => true, 'modified_by' => true,
            ],
            'validate' => 'update',

View on GitHub (pinned to 31c1bbc10f)