Troubleshooting

​

Problem

• There is no permission named 'edit articles' for guard 'web'.
• There is no role named 'writer' for guard 'web'.

​

Solutions

1. Verify the permission/role exists in the database
   php artisan permission:show
   
2. Check the guard name matches
   // Make sure the guard matches your config
   $permission = Permission::create(['name' => 'edit articles', 'guard_name' => 'web']);
   
3. Clear the cache after creating permissions
   php artisan permission:cache-reset
   

​

Problem

​

Solution

// When creating permissions/roles
$permission = Permission::create(['name' => 'edit articles', 'guard_name' => 'web']);
$role = Role::create(['name' => 'writer', 'guard_name' => 'web']);

// Or specify guard when assigning
$user->assignRole('writer', 'web');
$user->givePermissionTo('edit articles', 'web');

​

Problem

​

Solutions

1. Reset the permission cache
   php artisan permission:cache-reset
   
2. If you modified the database directly, always clear cache
   app()->make(\Spatie\Permission\PermissionRegistrar::class)->forgetCachedPermissions();
   
3. For Octane users, enable auto-reset in config
   // config/permission.php
   'register_octane_reset_listener' => true,
   

​

Problem

​

Debugging Steps

1. Check if user has the permission
   dd($user->getAllPermissions());
   dd($user->roles);
   
2. Verify middleware is configured correctly
   // In app/Http/Kernel.php (Laravel 10 and below)
   protected $middlewareAliases = [
       'role' => \Spatie\Permission\Middleware\RoleMiddleware::class,
       'permission' => \Spatie\Permission\Middleware\PermissionMiddleware::class,
   ];
   
3. Check if HasRoles trait is applied
   use Spatie\Permission\Traits\HasRoles;
   
   class User extends Authenticatable
   {
       use HasRoles;
   }
   

​

Problem

​

Solution

// Convert array of permission IDs from strings to integers
$permissionIds = collect($validated['permission'])->map(fn($val) => (int)$val);

$role->syncPermissions($permissionIds);

​

Problem

​

Solution

use Illuminate\Foundation\Auth\User as Authenticatable;
use Spatie\Permission\Traits\HasRoles;

class User extends Authenticatable
{
    use HasRoles;

    // ... rest of your model
}

​

Problem

• Index name too long errors on MySQL
• Duplicate column errors

​

Solutions

// In the migration, shorten column lengths
$table->string('name', 125); // instead of 255

Schema::create('permissions', function (Blueprint $table) {
    $table->engine = 'InnoDB';
    // ... rest of migration
});

php artisan migrate:status

​

Problem

​

Solution

// config/cache.php
'prefix' => env('CACHE_PREFIX', 'myapp_cache'),

// After switching tenants
app()->make(\Spatie\Permission\PermissionRegistrar::class)->initializeCache();

​

Problem

​

Solution

1. Enable wildcard permissions in config
   // config/permission.php
   'enable_wildcard_permission' => true,
   
2. Clear cache after enabling
   php artisan permission:cache-reset
   
3. Verify wildcard syntax
   $user->givePermissionTo('articles.*');
   $user->can('articles.edit'); // true
   

​

Problem

​

Solutions

1. Ensure you’ve run the teams migration
   php artisan permission:upgrade-teams
   
2. Set the team ID in your middleware
   setPermissionsTeamId($team->id);
   
3. Configure team resolver in config
   // config/permission.php
   'teams' => true,
   

​

Problem

​

Solution

// Load roles and permissions with users
$users = User::with('roles.permissions')->get();

// For a single user
$user->load('roles.permissions');

​

Problem

​

Solution

1. Clear cache in tests
   public function setUp(): void
   {
       parent::setUp();
       app()[\Spatie\Permission\PermissionRegistrar::class]->forgetCachedPermissions();
   }
   
2. Create permissions in your test setup
   Permission::create(['name' => 'edit articles']);
   Role::create(['name' => 'writer'])
       ->givePermissionTo('edit articles');