passbolt/passbolt_api · warning · BadRequestException

The group identifier should be a valid UUID.

Error message

The group identifier should be a valid UUID.

What it means

UUID guard in GroupGetService::getOrFail() (reached via getNotDeletedOrFail): the groupId must be a valid UUID before any lookup. Fires when callers pass a malformed group identifier, rejecting with HTTP 400; a well-formed id for a missing group raises the subsequent NotFoundException instead.

Solutions

1. Ensure the client uses the group's UUID from the API listing (/groups)
2. Validate id format client-side with a UUID regex before calling
3. URL-encode ids correctly and avoid manual string truncation

Example fix

// before
deleteGroup('finance-team');
// after
deleteGroup('b5b5c8c0-1234-4c4c-8c8c-123456789abc');

const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
if (!UUID_RE.test(groupId)) throw new Error(`groupId must be a UUID, got: ${groupId}`);

const isGroupUuid = (v: unknown): v is string =>
  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.get(`/groups/${groupId}`);
} catch (e) {
  if (e.response?.status === 400) throw new Error('Group id must be a valid UUID');
  throw e;
}

When it happens

Trigger: Calling any endpoint resolving a group by id (e.g. GET/PUT/DELETE /groups/{id}) where {id} is not a UUID — a name, slug, empty string, or malformed id.

Common situations: Client passing the group name instead of its id, truncated or URL-unescaped ids, older API clients that used string identifiers before UUIDs were enforced.

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 comment id is not valid.
• The group id is not valid.
• The identifier should be a valid UUID.
• The resource identifier should be a valid UUID.
• The resource identifier should be a valid UUID.

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

Appendix: source

Thrown at src/Service/Groups/GroupGetService.php:60

     * GroupGetService constructor
     */
    public function __construct()
    {
        $this->groupsTable = TableRegistry::getTableLocator()->get('Groups');
    }

    /**
     * Get a group by ID or throw relevant HTTP exception.
     *
     * @param string $groupId The identifier of the group to get
     * @return \App\Model\Entity\Group
     * @throws \Cake\Http\Exception\BadRequestException If the group identifier is not a valid UUID.
     * @throws \Cake\Http\Exception\NotFoundException If the group does not exist.
     */
    protected function getOrFail(string $groupId): Group
    {
        if (!Validation::uuid($groupId)) {
            throw new BadRequestException(__('The group identifier should be a valid UUID.'));
        }

        try {
            $group = $this->groupsTable->get($groupId);
        } catch (RecordNotFoundException $exception) {
            throw new NotFoundException(__('The group does not exist.'));
        }

        return $group;
    }

    /**
     * Get a group by ID or throw relevant HTTP exception.
     *
     * @param string $groupId The identifier of the group to get
     * @return \App\Model\Entity\Group
     * @throws \Cake\Http\Exception\NotFoundException If the group does not exist or is soft deleted
     */

View on GitHub (pinned to 31c1bbc10f)