passbolt/passbolt_api · error · InvalidArgumentException

The metadata key ID should be a valid UUID.

Error message

The metadata key ID should be a valid UUID.

What it means

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.

Solutions

1. Pass a valid metadata key UUID obtained from GET /metadata/keys.json or the metadata_keys table.
2. Validate the identifier with Cake\Validation\Validation::uuid($metadataKeyId) before calling the service.
3. 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.
4. Ensure the value is a non-empty string; cast/null-check before invoking the usage assertion.

Example fix

// before
$service->isKeyInUse($keyName); // "corp-key" — not a UUID

// after
if (!Validation::uuid($metadataKeyId)) {
    throw new InvalidArgumentException("Invalid metadata key id: $metadataKeyId");
}
$service->isKeyInUse($metadataKeyId);

use Cake\Validation\Validation;
if (!is_string($metadataKeyId) || !Validation::uuid($metadataKeyId)) {
    throw new InvalidArgumentException('metadata key id must be a valid UUID string');
}

function isValidMetadataKeyId(mixed $v): bool {
    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;
}

try {
    $isUsed = $service->isKeyInUse($metadataKeyId);
} catch (InvalidArgumentException $e) {
    // resolve the key name/slug to its UUID first, then retry
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• Invalid user ID format.
• Invalid verify token format.
• The identifier should be a valid UUID.
• The identifier should be a valid UUID.
• The parent task identifier should be a valid UUID.

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

Appendix: source

Thrown at plugins/PassboltCe/Metadata/src/Service/MetadataKey/MetadataKeyAssertUsageService.php:38

use Cake\ORM\Locator\LocatorAwareTrait;
use Cake\ORM\Query;
use Cake\Validation\Validation;
use InvalidArgumentException;

class MetadataKeyAssertUsageService
{
    use LocatorAwareTrait;

    /**
     * @param string $metadataKeyId key uuid
     * @param bool $assertKeyId assert key id default true
     * @return void
     * @throws \InvalidArgumentException if $metadataKeyId is not a valid uuid
     */
    private function assertKeyId(string $metadataKeyId, bool $assertKeyId = true): void
    {
        if ($assertKeyId && !Validation::uuid($metadataKeyId)) {
            throw new InvalidArgumentException(__('The metadata key ID should be a valid UUID.'));
        }
    }

    /**
     * @param \Cake\ORM\Query $query query on the table to perform the assertion of usage on
     * @param string $metadataKeyId key uuid
     * @param bool $assertKeyId assert key id default true
     * @return bool if some tags are using the metadata key
     * @throws \InvalidArgumentException if $metadataKeyId is not a valid uuid and assertKeyId true
     */
    private function isUsedByTable(Query $query, string $metadataKeyId, bool $assertKeyId = true): bool
    {
        $this->assertKeyId($metadataKeyId, $assertKeyId);

        return $query
                ->where(['metadata_key_id' => $metadataKeyId])
                ->all()
                ->count() > 0;

View on GitHub (pinned to 31c1bbc10f)