passbolt/passbolt_api · error · BadRequestException

The role identifier is not valid.

Error message

The role identifier is not valid.

What it means

Thrown by RolesUpdateController::update() when the roleId path parameter fails CakePHP's Validation::uuid() check before any service logic runs. It is a request-sanity guard: role updates are only addressable by a valid UUID, so a malformed identifier is rejected as a 400 Bad Request without touching the database.

Solutions

1. Validate the role id with a UUID check on the client before calling the endpoint
2. Look up the role id from the GET /roles.json listing instead of using a name or slug
3. Fix id construction/interpolation in the calling code (check for truncation or wrong variable)
4. Ensure the request targets PUT /roles/{uuid}.json with the id in the path, not the body

Example fix

// before
await api.put(`/roles/${roleName}.json`, data); // roleName = 'admin'
// after
const roles = await api.get('/roles.json');
const role = roles.body.find(r => r.name === roleName);
if (!isUuid(role.id)) throw new Error('invalid role id');
await api.put(`/roles/${role.id}.json`, data);

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(roleId)) throw new Error(`invalid role id: ${roleId}`);

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(`/roles/${roleId}.json`, data); }
catch (e) { if (e.response?.status === 400) { /* resolve id from /roles.json and retry */ } else throw e; }

When it happens

Trigger: Calling PUT /roles/<id>.json where <id> is not a UUID v4 string — e.g. a role name like 'admin', a slug, a truncated id, or an empty segment.

Common situations: Client code passing role names instead of ids; hard-coded or copy-pasted ids with typos; older integrations built against an API that accepted names; string concatenation dropping part of the id.

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 request data is invalid: id invalid.
• The resource identifier should be a valid UUID.
• Invalid id
• Please provide a valid request id.
• The authentication token id is invalid.

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

Appendix: source

Thrown at src/Controller/Roles/RolesUpdateController.php:37

use App\Controller\AppController;
use App\Service\Roles\RolesUpdateService;
use Cake\Http\Exception\BadRequestException;
use Cake\Validation\Validation;

class RolesUpdateController extends AppController
{
    /**
     * @param string $roleId Role identifier to update.
     * @return void
     */
    public function update(string $roleId): void
    {
        $this->assertJson();
        $this->User->assertIsAdmin();

        if (!Validation::uuid($roleId)) {
            throw new BadRequestException(__('The role identifier is not valid.'));
        }

        $result = (new RolesUpdateService())->update(
            $this->User->getAccessControl(),
            $roleId,
            $this->getRequest()->getData()
        );

        $this->success(__('The role was successfully updated.'), $result);
    }
}

View on GitHub (pinned to 31c1bbc10f)