{"record":{"id":"7ccfc0e9449e40d5","repo":"BookStackApp/BookStack","slug":"errors-role-registration-default-cannot-delete","errorCode":null,"errorMessage":"errors.role_registration_default_cannot_delete","messagePattern":"errors\\.role_registration_default_cannot_delete","errorType":"exception","errorClass":"PermissionsException","httpStatus":null,"severity":"error","filePath":"app/Permissions/PermissionsRepo.php","lineNumber":136,"sourceCode":"\n    /**\n     * Delete a role from the system.\n     * Check it's not an admin role or set as default before deleting.\n     * If a migration Role ID is specified, the users assigned to the current role\n     * will be added to the role of the specified id.\n     *\n     * @throws PermissionsException\n     * @throws Exception\n     */\n    public function deleteRole(int $roleId, int $migrateRoleId = 0): void\n    {\n        $role = $this->getRoleById($roleId);\n\n        // Prevent deleting admin role or default registration role.\n        if ($role->system_name && in_array($role->system_name, $this->systemRoles)) {\n            throw new PermissionsException(trans('errors.role_system_cannot_be_deleted'));\n        } elseif ($role->id === intval(setting('registration-role'))) {\n            throw new PermissionsException(trans('errors.role_registration_default_cannot_delete'));\n        }\n\n        (new DatabaseTransaction(function () use ($migrateRoleId, $role) {\n            if ($migrateRoleId !== 0) {\n                $newRole = Role::query()->find($migrateRoleId);\n                if ($newRole) {\n                    $users = $role->users()->pluck('id')->toArray();\n                    $newRole->users()->sync($users);\n                }\n            }\n\n            $role->entityPermissions()->delete();\n            $role->jointPermissions()->delete();\n            Activity::add(ActivityType::ROLE_DELETE, $role);\n            $role->delete();\n        }))->run();\n    }\n}","sourceCodeStart":118,"sourceCodeEnd":154,"githubUrl":"https://github.com/BookStackApp/BookStack/blob/18f8469a1c72f8cc8497e9372635e6dea5028071/app/Permissions/PermissionsRepo.php#L118-L154","documentation":"PermissionsRepo::deleteRole also blocks deletion of the role configured as the default role for new registrations (setting 'registration-role'). Deleting it would leave new sign-ups without a valid role, so a PermissionsException is thrown.","triggerScenarios":"Calling deleteRole($roleId) where $role->id equals intval(setting('registration-role')); also occurs via the role-management UI when deleting the default registration role.","commonSituations":"Admins cleaning up unused roles without realizing one is the registration default; scripts bulk-deleting roles after a migration; environments where the setting points at an unexpected role.","solutions":["Change the default registration role first (Settings > Registration > Default user role, or setting 'registration-role') to another role, then delete the old one","Skip the default-registration role in bulk-delete scripts the same way system roles are skipped","If the setting points to the wrong role id, correct the setting value in the settings table","Check the error vs. error 121: if it's not a system role, it's this registration-default check"],"exampleFix":"// before\n$repo->deleteRole($oldRoleId);\n// after\nif (intval(setting('registration-role')) !== $oldRoleId) {\n    $repo->deleteRole($oldRoleId);\n} else {\n    // set another role as registration default first\n}","handlingStrategy":"validation","validationCode":"$defaultRegRole = intval(setting('registration-role'));\nif ($roleId === $defaultRegRole) {\n    throw new \\InvalidArgumentException('Change the default registration role before deleting this role');\n}","typeGuard":"function isDefaultRegistrationRole(int $roleId, $settings): bool {\n    return $roleId === intval($settings->get('registration-role'));\n}","tryCatchPattern":"try {\n    $repo->deleteRole($roleId);\n} catch (\\BookStack\\Exceptions\\PermissionsException $e) {\n    if (str_contains($e->getMessage(), 'role_registration_default_cannot_delete')) {\n        // prompt admin to pick a new default registration role first\n    }\n}","preventionTips":["Verify the 'registration-role' setting points at an intended role after migrations","When deleting a role, reassign the registration default first in Settings > Registration","Skip the registration-default role in bulk-delete scripts","Audit settings table for stale role ids after imports"],"tags":["permissions","roles","configuration","bookstack"],"backgroundTag":"default-role-delete-forbidden","analyzedSha":"18f8469a1c72f8cc8497e9372635e6dea5028071","analyzedAt":"2026-09-02T19:49:33.068Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-10T02:17:09.455Z"}