passbolt/passbolt_api · error · BadRequestException

The private key identifier should be a UUID.

Error message

The private key identifier should be a UUID.

What it means

UUID guard in MetadataPrivateKeysUpdateController::update(): the {id} path segment must be a valid UUID of the metadata private key record to update. Fires when the client passes a malformed identifier, so the update is aborted with HTTP 400 before touching the service layer. A syntactically valid UUID that does not exist is handled later as a not-found error.

Solutions

1. Use the metadata private key UUID (from GET /metadata/private-keys or key detail responses).
2. Resolve the correct id via the API before updating.
3. Add UUID validation client-side.

Example fix

// before
put(`/metadata/private-keys/${userId}`, data);
// after
put(`/metadata/private-keys/${privateKeyId}`, data);

if (!isUuid(privateKeyId)) throw new Error('private key id must be a UUID');

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/private-keys/${privateKeyId}`, data); } catch (e) { if (e.response?.status === 400 && String(e.message).includes('UUID')) { privateKeyId = await resolvePrivateKeyId(); return retry(); } throw e; }

When it happens

Trigger: Updating a metadata private key where {id} is not a valid UUID (e.g. a user id or key fingerprint was used).

Common situations: Confusing the metadata private key id with the user id or metadata key id; stale/hand-edited URLs; scripts iterating wrong id field.

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 ID should be a valid UUID.
• The metadata 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/74e7e2e2129b179e. Report an issue: GitHub.

Appendix: source

Thrown at plugins/PassboltCe/Metadata/src/Controller/MetadataPrivateKeysUpdateController.php:38

use Cake\Http\Exception\BadRequestException;
use Cake\Validation\Validation;
use Passbolt\Metadata\Service\MetadataPrivateKeysUpdateService;

class MetadataPrivateKeysUpdateController extends AppController
{
    /**
     * Update a user private key
     *
     * @param string $id private key id
     * @return void
     */
    public function update(string $id)
    {
        $this->assertJson();
        $this->assertNotEmptyArrayData();

        if (!Validation::uuid($id)) {
            throw new BadRequestException(__('The private key identifier should be a UUID.'));
        }
        $data = $this->request->getData();

        $updated = (new MetadataPrivateKeysUpdateService())->update($this->User->getAccessControl(), $id, $data);
        $this->success(__('The operation was successful.'), $updated);
    }
}

View on GitHub (pinned to 31c1bbc10f)