{"record":{"id":"2533c247200740c9","repo":"passbolt/passbolt_api","slug":"the-metadata-key-id-should-be-a-valid-uuid-2533c2","errorCode":null,"errorMessage":"The metadata key ID should be a valid UUID.","messagePattern":"The metadata key ID should be a valid UUID\\.","errorType":"exception","errorClass":"InvalidArgumentException","httpStatus":500,"severity":"error","filePath":"plugins/PassboltCe/Metadata/src/Service/MetadataKey/MetadataKeyAssertUsageService.php","lineNumber":38,"sourceCode":"use Cake\\ORM\\Locator\\LocatorAwareTrait;\nuse Cake\\ORM\\Query;\nuse Cake\\Validation\\Validation;\nuse InvalidArgumentException;\n\nclass MetadataKeyAssertUsageService\n{\n    use LocatorAwareTrait;\n\n    /**\n     * @param string $metadataKeyId key uuid\n     * @param bool $assertKeyId assert key id default true\n     * @return void\n     * @throws \\InvalidArgumentException if $metadataKeyId is not a valid uuid\n     */\n    private function assertKeyId(string $metadataKeyId, bool $assertKeyId = true): void\n    {\n        if ($assertKeyId && !Validation::uuid($metadataKeyId)) {\n            throw new InvalidArgumentException(__('The metadata key ID should be a valid UUID.'));\n        }\n    }\n\n    /**\n     * @param \\Cake\\ORM\\Query $query query on the table to perform the assertion of usage on\n     * @param string $metadataKeyId key uuid\n     * @param bool $assertKeyId assert key id default true\n     * @return bool if some tags are using the metadata key\n     * @throws \\InvalidArgumentException if $metadataKeyId is not a valid uuid and assertKeyId true\n     */\n    private function isUsedByTable(Query $query, string $metadataKeyId, bool $assertKeyId = true): bool\n    {\n        $this->assertKeyId($metadataKeyId, $assertKeyId);\n\n        return $query\n                ->where(['metadata_key_id' => $metadataKeyId])\n                ->all()\n                ->count() > 0;","sourceCodeStart":20,"sourceCodeEnd":56,"githubUrl":"https://github.com/passbolt/passbolt_api/blob/31c1bbc10f32808a607fa9bd81891e898779c0bc/plugins/PassboltCe/Metadata/src/Service/MetadataKey/MetadataKeyAssertUsageService.php#L20-L56","documentation":"MetadataKeyAssertUsageService::assertKeyId validates that the $metadataKeyId string passed to its usage-assertion queries is a valid UUID and throws InvalidArgumentException otherwise. All isKeyInUse/isUsedByTable checks funnel through it, guaranteeing usage queries never run against malformed key identifiers.","triggerScenarios":"Calling isKeyInUse / isUsedByTable (e.g. before metadata key deletion, in MetadataKeysDeleteService) with a string that is not a UUID — empty string, numeric ID, slug, or a UUID-like string with wrong length/format.","commonSituations":"CLI commands or scripts passing key short-IDs or names instead of UUIDs; IDs extracted incorrectly from config or environment variables (empty string); unit tests exercising assertKeyId with placeholder values.","solutions":["Pass a valid metadata key UUID obtained from GET /metadata/keys.json or the metadata_keys table.","Validate the identifier with Cake\\Validation\\Validation::uuid($metadataKeyId) before calling the service.","Fix upstream value sources (env vars, CLI args, config) so they supply full 8-4-4-4-12 hex UUIDs, not names or numeric IDs.","Ensure the value is a non-empty string; cast/null-check before invoking the usage assertion."],"exampleFix":"// before\n$service->isKeyInUse($keyName); // \"corp-key\" — not a UUID\n\n// after\nif (!Validation::uuid($metadataKeyId)) {\n    throw new InvalidArgumentException(\"Invalid metadata key id: $metadataKeyId\");\n}\n$service->isKeyInUse($metadataKeyId);","handlingStrategy":"type-guard","validationCode":"use Cake\\Validation\\Validation;\nif (!is_string($metadataKeyId) || !Validation::uuid($metadataKeyId)) {\n    throw new InvalidArgumentException('metadata key id must be a valid UUID string');\n}","typeGuard":"function isValidMetadataKeyId(mixed $v): bool {\n    return is_string($v) && preg_match('/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i', $v) === 1;\n}","tryCatchPattern":"try {\n    $isUsed = $service->isKeyInUse($metadataKeyId);\n} catch (InvalidArgumentException $e) {\n    // resolve the key name/slug to its UUID first, then retry\n}","preventionTips":["Always source key ids from the metadata_keys table or GET /metadata/keys.json","Never pass key names, slugs, or numeric ids where a UUID is expected","Check env/config sources for empty-string defaults before passing ids","Add Validation::uuid() assertions at the boundary of CLI commands and scripts"],"tags":["passbolt","metadata-key","uuid","invalid-argument","validation"],"backgroundTag":"invalid-argument-format","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"}