{"record":{"id":"eb73806867f6c2a8","repo":"passbolt/passbolt_api","slug":"the-metadata-key-fingerprint-is-invalid","errorCode":null,"errorMessage":"The metadata key fingerprint is invalid.","messagePattern":"The metadata key fingerprint is invalid\\.","errorType":"http","errorClass":"NotFoundException","httpStatus":404,"severity":"error","filePath":"plugins/PassboltCe/Metadata/src/Service/MetadataKey/MetadataKeyUpdateService.php","lineNumber":67,"sourceCode":"        $uac->assertIsAdmin();\n\n        if (!Validation::uuid($id)) {\n            throw new BadRequestException(__('The metadata key ID should be a valid UUID.'));\n        }\n\n        $metadataKeysTable = $this->fetchTable('Passbolt/Metadata.MetadataKeys');\n\n        // Assert the key exist\n        try {\n            /** @var \\Passbolt\\Metadata\\Model\\Entity\\MetadataKey $metadataKey */\n            $metadataKey = $metadataKeysTable->get($id);\n        } catch (RecordNotFoundException $exception) { // @phpstan-ignore-line\n            throw new NotFoundException(__('The metadata key does not exist or has been deleted.'), 404, $exception);\n        }\n\n        // Assert fingerprint is the same\n        if ($metadataKey->fingerprint !== $dto->fingerprint) {\n            throw new NotFoundException(__('The metadata key fingerprint is invalid.'));\n        }\n\n        // Assert the key is not already deleted\n        if ($metadataKey->isDeleted()) {\n            throw new NotFoundException(__('The metadata key has already been deleted.'));\n        }\n\n        // Assert they key was not previously marked as expired\n        if ($metadataKey->isExpired()) {\n            throw new BadRequestException(__('The metadata key is already marked as expired.'));\n        }\n\n        // Patch the key deleted field with the current time\n        $options = [\n            'accessibleFields' => [\n                'fingerprint' => true, 'armored_key' => true, 'expired' => true, 'modified_by' => true,\n            ],\n            'validate' => 'update',","sourceCodeStart":49,"sourceCodeEnd":85,"githubUrl":"https://github.com/passbolt/passbolt_api/blob/31c1bbc10f32808a607fa9bd81891e898779c0bc/plugins/PassboltCe/Metadata/src/Service/MetadataKey/MetadataKeyUpdateService.php#L49-L85","documentation":"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).","triggerScenarios":"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.","commonSituations":"Client mixes up two keys during rotation; fingerprint case or whitespace differences (passbolt fingerprints are uppercase); stale DTO built from an older key version.","solutions":["Send the exact fingerprint returned by GET /metadata/keys for that id (same casing, no whitespace)","Make sure the id and fingerprint in the request both refer to the same key","If intending to replace a key, use the rotation flow instead of the update endpoint"],"exampleFix":"// before\nawait updateMetadataKey(keyA.id, { fingerprint: keyB.fingerprint });\n// after\nawait updateMetadataKey(keyA.id, { fingerprint: keyA.fingerprint });","handlingStrategy":"validation","validationCode":"const key = await getMetadataKey(id);\nif (dto.fingerprint !== key.fingerprint) {\n  throw new Error('fingerprint does not match key');\n}","typeGuard":null,"tryCatchPattern":"try {\n  await updateMetadataKey(id, dto);\n} catch (e) {\n  if (e.status === 404 && /fingerprint is invalid/.test(e.message)) {\n    dto.fingerprint = (await getMetadataKey(id)).fingerprint;\n    return updateMetadataKey(id, dto);\n  }\n  throw e;\n}","preventionTips":["Copy the fingerprint verbatim from the API response (respect casing)","Ensure id and fingerprint in one request refer to the same key","Use the rotation flow to change keys rather than the update endpoint"],"tags":["fingerprint","metadata-keys","not-found","mismatch"],"backgroundTag":"invalid-argument-value","analyzedSha":"31c1bbc10f32808a607fa9bd81891e898779c0bc","analyzedAt":"2026-09-17T00:04:38.960Z","contentChangedAt":"2026-09-17T00:04:38.960Z","schemaVersion":2},"datasetVersion":"2026-09-21T04:17:39.646Z"}