spatie/laravel-permission There is no permission named `edit_project` for guard `api`

spatie/laravel-permission There is no permission named `edit_project` for guard `api`

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

Stefan Bogdanescu

Founder & Senior Architect

spatie/laravel-permission There is no permission named edit_project for guard api

When working with Laravel Passport and the spatie/laravel-permission package, a common friction point arises when assigning permissions to roles intended for API authentication. If you encounter the error There is no permission named edit_project for guard api, the issue isn't necessarily with your logic or the specific permission string itself. It stems from how the package indexes permissions and how Passport interacts with that index.

The error message explicitly points to a missing entry in the internal cache of available permissions for the specified guard. In your scenario, you are defining permissions like edit_project but assigning them to the api guard. The root cause is almost always found in the guard_name column of the permission table.

Understanding the Guard Mismatch

The spatie/laravel-permission package uses a two-table approach. The permissions table stores the unique identifiers for actions (like edit_project, delete_project) and, crucially, which guard they belong to. The role_permissions junction table links users or roles to these specific permission-guar combinations.

When you look at your seeder output, the permissions were initially seeded against the web guard. This means the database contains records where guard_name = 'web'. When your application attempts to assign these same permission strings to a role using the api guard, the package queries for an entry matching both the permission name and the api guard.

Since the database only knows about the web guard for those specific permission names, the query fails, resulting in the exception you are seeing. Manually updating the guard_name column in your migration file or directly in the database to 'api' resolves this immediately. However, manually altering production data is a bad practice and bypasses the intended lifecycle of your application's configuration.

The Correct Approach: Seeder Configuration

The robust solution lies in ensuring your permission seeder initializes with the correct guard from the start. You should inspect your database/migrations/xxxx_xx_xx_create_permissions_table.php file to ensure it creates the necessary columns for multiple guards if needed, or simply seeds the correct guard during your initial setup.

More importantly, review your PermissionSeeder. Instead of hardcoding a single permission string like 'edit_project', you should define an array that explicitly includes the guard name. In version 2.x and 3.x of the package, permissions are often defined as strings, but when dealing with multiple guards, you must ensure the data being seeded matches the configuration in config/auth.php.

Here is a pattern for how your seeder logic should look to avoid this mismatch:

use Spatie\Permission\Models\Role;
use Spatie\Permission\Models\Permission;

public function run()
{
    // Define permissions specifically for the API guard
    $projectPermissions = [
        'edit_project',
        'add_project',
        'delete_project',
    ];

    foreach ($projectPermissions as $permission) {
        Permission::firstOrCreate(
            ['name' => $permission, 'guard_name' => config('auth.guards.api.driver') === 'passport' ? 'api' : null], 
            // Note: In standard spatie usage, permissions are usually seeded per guard.
            // If you want these to exist for the API guard specifically:
        );
    }

    // Or simply ensure you create them with the correct guard_name explicitly
    $permissions = [
        'edit_project',
        'add_project',
        'delete_project',
    ];

    foreach ($permissions as $permission) {
        Permission::firstOrCreate(
            ['name' => $permission, 'guard_name' => 'api'], 
            // You can add column defaults here if needed
        );
    }

    // Create a role and assign the permissions
    $role = Role::create(['name' => 'project_manager']);
    
    // This will now work because the permission exists for the 'api' guard
    $role->givePermissionTo($permissions);
}

Why This Happens with Passport

Laravel Passport uses tokens rather than sessions. The api guard in config/auth.php is configured to use the passport driver. When you define permissions, they are inherently tied to a specific authentication context. If your seeder runs on a fresh instance where no specific guard configuration for API permissions exists, it defaults to whatever is explicitly passed or defaults to 'web' if not specified carefully in the migration seeders.

When you manually change the guard_name in the database, you are effectively telling the package: "Treat these actions as valid for the API authentication flow." While this fixes the immediate error, the seeder approach ensures that every time you reset your environment or deploy, the permissions align correctly with your auth.php configuration without requiring manual SQL intervention.

Final Checklist

If you continue to face issues after seeding:

  1. Verify config/auth.php has the api guard defined with 'driver' => 'passport'.
  2. Ensure your seeder explicitly sets 'guard_name' => 'api' when creating permissions intended for API routes.
  3. Clear your application cache (php artisan cache:clear) and config cache if changes don't reflect immediately, though this specific error is usually a hard database state issue.

By aligning your permission definitions with the configured guards in your auth.php, you eliminate the ambiguity that triggers the "no permission named" exception.

Our network