Troubleshooting and FAQ

Access denied on the admin screens#

You are redirected to /dashboard with "Access Denied. You do not have sufficient privileges."

Check your user has a role:
PHP
```
\BabeRuka\SystemRoles\Services\SystemRolesService::roleIdForUser(auth()->id());
```
0 means no row in user_roles. Create one (see Installation step 6).
Check that role is the super admin:
PHP
```
config('systemroles.super_admin_role_id');
```
If your super admin has another id, set SYSTEMROLES_SUPER_ADMIN_ROLE_ID.
Clear cached config: php artisan config:clear.

Redirected to `/login` in a loop#

super_admin sends guests to login_url (default /login). If your login page lives elsewhere, set SYSTEMROLES_LOGIN_URL.

The admin screens have no styling#

Publish the assets:

Bash

php artisan vendor:publish --tag=systemroles-assets --force

Check that public/vendor/systemroles/addons/bootstrap/5.2.3/css/bootstrap.min.css exists and is readable by the web server.

"Route [logout] not defined"#

The admin layout posts to a route named logout. Install an auth starter kit, define a logout route, or publish the views and change the top bar and sidebar partials.

"This screen is not available yet"#

The Routes and Menus screens don't ship with views yet. See Route Access and Menus.

Migrations fail with a foreign key error on `users`#

user_roles.user_id and user_roles_in.user_id are BIGINT UNSIGNED foreign keys to users.id. Your users.id must be the same type. Check with:

SQL

SHOW COLUMNS FROM users LIKE 'id';

"Cannot delete or update a parent row" when deleting a user#

The user still has rows in user_roles or user_roles_in. Delete those first, or use soft deletes for users.

The provider is not found#

The provider class is BabeRuka\SystemRoles\Providers\SystemRolesServiceProvider. Older instructions listed BabeRuka\SystemRoles\SystemRolesServiceProvider, which does not exist.

Permission changes don't apply to a user#

If you read permissions from the session, the user must log in again, or call userPermissions($roleId, true).
If you cache permissions yourself, clear the cache key for that role.
roleHas() always reads the live matrix.

`roleHas()` returns `false` for a permission I can see#

Check the row for that role is switched on (in_role = '1'). Each role has its own row.
Check the name: roleHas() compares exactly with in_guard_name or in_name. Guard names are stored lower case.
Check the user's role: roleIdForUser(). Remember that in user_roles, role_id is the row id and user_role is the role.

The Classes screen is slow#

Scanning runs each time the screen opens. Set SYSTEMROLES_SCAN_ON_REQUEST=false and run php artisan systemroles:sync --classes after deploys.

A deleted controller or route still shows#

Scans only add and update. Delete old rows by hand (remove their *_in rows first).

FAQ#

Can a user have more than one role? No. Each user has one row in user_roles. Create a combined role if you need one.

Does it support teams or tenants? Not built in. For per-tenant roles, keep separate role sets per tenant (for example by naming convention) or add a tenant column in your own migration.

Does it work with Sanctum / API tokens? Yes. The checks take a user id, so they work with any guard. Use $request->user() in your middleware.

Can I use it with Spatie Laravel Permission at the same time? Technically yes, they use different tables. In practice, pick one source of truth. See Migrating.

Does it work with Livewire, Inertia or a SPA? Yes. Check permissions on the server (middleware, controllers, Livewire actions) and send the permission list to the front end for display. See In API resources and JSON.

Is there a UI to delete roles or permissions? Not yet. See Roles → Deleting a role and Permissions → Deleting a permission.