The given role or permission should use guard `` instead of `web`. -Laravel

The given role or permission should use guard `` instead of `web`. -Laravel

  1. Blog
  2. 15 November 2026
  3. 4 min read

Stefan Bogdanescu

Founder & Senior Architect

The given role or permission should use guard `` instead of web

When integrating Spatie's HasRoles trait into a Laravel application, you might encounter a specific validation error that halts role assignment: "The given role or permission should use guard `` instead of web". This message indicates a fundamental mismatch between the authentication guard your application expects and the one configured on the role itself.

This issue typically arises when you are building an API-based application but have not explicitly defined a separate guard for that context, or if Spatie's default configuration is being overridden incorrectly. The error prevents you from assigning roles because the assignRole method checks the guard associated with the role against the current authentication strategy defined in your config/auth.php.

Understanding the Guard Mismatch

In Laravel, a "guard" defines how users are authenticated and who can access the application. The default setup usually involves a web guard that uses sessions for desktop browsers and an api guard that uses tokens for REST APIs.

When you create a role using Spatie's model builder or migrations, the package defaults to the first guard listed in your config/auth.php. If your auth.php file defines web as the primary guard (which is standard for web apps), Spatie assigns the web guard to new roles automatically.

However, the error message suggests that your application logic expects a different guard, or conversely, that you are attempting to assign a role to a user model that belongs to a guard that does not exist in your configuration. If you are working with a token-based authentication system (like Sanctum or Passport) and haven't explicitly configured an api guard with a matching provider, Spatie might be looking for a guard named `` (empty string), which implies it found a role with no guard assigned while your user model is tied to a specific guard.

Diagnosing the Configuration

To resolve this, you must inspect your config/auth.php file. Look closely at the guards array and ensure that the guard name used by Spatie matches one of your defined guards.

If you are building an API application where users authenticate via tokens, your configuration should look something like this:

'guards' => [
    'web' => [
        'driver' => 'session',
        'provider' => 'users',
    ],

    // Ensure this guard is defined if you plan to use it for roles
    'api' => [
        'driver' => 'token',
        'provider' => 'users',
    ],
],

If your Spatie role was created with the web guard, but your application logic (perhaps in a policy or middleware) expects the api guard, you will see this conflict. The solution is often to explicitly set the guard on the role when creating it:

$role = Role::create(['name' => 'admin']);
$role->guard_name = 'api'; // Explicitly set the guard
$user->assignRole($role);

Alternatively, if you are using the model builder directly in a controller or migration, ensure you are referencing the correct guard name. If you haven't defined an api guard but need token authentication, Spatie might default to an empty string if it cannot find a matching configuration, triggering the error.

Updating Existing Roles

If you have already created roles with the wrong guard or if the default behavior has locked them into an incorrect state, you can update the guard name directly on the role model. This is crucial when migrating from a web-only setup to an API-first architecture.

$role = Role::find($roleId);
$role->guard_name = 'api';
$role->save();

After updating the role's guard, re-assign it to the user:

$user->syncRoles(['admin']); // Or use assignRole if necessary

Common Pitfalls

One frequent mistake is assuming that defining a guard in config/auth.php automatically links Spatie roles to it. Spatie looks for the guard_name property on the role model. If you create a role via migration without specifying the guard, it inherits the default, which is usually web. If your application logic assumes api, this mismatch causes the error immediately upon assignment.

Another scenario involves using Laravel Sanctum. If you are authenticating via tokens but haven't registered the api guard correctly in your config/auth.php, Spatie might fail to resolve a valid guard name, resulting in the empty string error. Ensure that your User model is configured to use the token driver if you intend to use the api guard:

// In User model constructor or boot method
$this->guard_name = 'api';

By aligning the guard_name property of your roles with the guards defined in your auth.php configuration, you ensure that permission checks work seamlessly across both web and API contexts.

Our network