spatie/laravel-permission · warning

Teams feature disabled, argument --team-id has no effect. Ei

Error message

Teams feature disabled, argument --team-id has no effect. Either enable it in permissions config file or remove --team-id parameter

What it means

The permission:create-role command accepts a --team-id option that is only honored when the teams feature is enabled (PermissionRegistrar::$teams, driven by config('permission.teams')). When teams is off but --team-id was passed, the command prints this warning and returns SUCCESS immediately — the role is NOT created and no permissions are attached. The early return prevents creating a role that would silently ignore the requested team scope. Note the command also sets the permissions team id from --team-id before this check, so running it in-process can leak team context even though creation is skipped.

Source

Thrown at src/Commands/CreateRoleCommand.php:29

class CreateRoleCommand extends Command
{
    protected $signature = 'permission:create-role
        {name : The name of the role}
        {guard? : The name of the guard}
        {permissions? : A list of permissions to assign to the role, separated by | }
        {--team-id=}';

    protected $description = 'Create a role';

    public function handle(PermissionRegistrar $permissionRegistrar): int
    {
        $roleClass = app(RoleContract::class);

        $teamIdAux = getPermissionsTeamId();
        setPermissionsTeamId($this->option('team-id') ?: null);

        if (! $permissionRegistrar->teams && $this->option('team-id')) {
            $this->warn('Teams feature disabled, argument --team-id has no effect. Either enable it in permissions config file or remove --team-id parameter');

            return self::SUCCESS;
        }

        $role = $roleClass::findOrCreate($this->argument('name'), $this->argument('guard'));
        setPermissionsTeamId($teamIdAux);

        $teams_key = $permissionRegistrar->teamsKey;
        if ($permissionRegistrar->teams && $this->option('team-id') && is_null($role->$teams_key)) {
            $this->warn("Role `{$role->name}` already exists on the global team; argument --team-id has no effect");
        }

        $role->givePermissionTo($this->makePermissions($this->argument('permissions')));

        $this->info("Role `{$role->name}` ".($role->wasRecentlyCreated ? 'created' : 'updated'));

        return self::SUCCESS;
    }

View on GitHub (pinned to afd24018f6)

Solutions

1. Remove the --team-id option: php artisan permission:create-role writer web "edit posts"
2. If you really want team-scoped roles, enable teams: set 'teams' => true in config/permission.php, run php artisan permission:setup-teams, migrate, then re-run the command with --team-id
3. Confirm the live flag with `php artisan tinker` → config('permission.teams') and clear the config cache (php artisan config:clear) after edits

Example fix

# before
php artisan permission:create-role writer web "edit posts" --team-id=2
# exits 0 with the warning; no role created

# after (teams disabled)
php artisan permission:create-role writer web "edit posts"

// skip --team-id unless the feature is actually on
$teamsEnabled = app(\Spatie\Permission\PermissionRegistrar::class)->teams;
$options = ($teamsEnabled && $teamId) ? ['--team-id' => $teamId] : [];
\Illuminate\Support\Facades\Artisan::call('permission:create-role', [
    'name' => 'writer',
    'guard' => 'web',
    'permissions' => 'edit posts',
] + $options);

When it happens

Trigger: Running `php artisan permission:create-role writer web "perm1|perm2" --team-id=X` while config('permission.teams') is false. Any truthy --team-id value together with the disabled feature hits the early return before findOrCreate() runs.

Common situations: Same command reused across environments where only some have teams enabled; a seeder/deploy script carrying --team-id from a multi-tenant phase of the project; teams turned off in config while old documentation or scripts still pass the flag.

Related errors

• Teams feature disabled, argument --team-id has no effect. Ei
• Please enable the teams setting in your configuration.
• Role `{$role->name}` already exists on the global team; argu
• Setup teams migration already exists. Following file was fou
• Unsupported type for $roles parameter to hasRole().

AI-assisted analysis of spatie/laravel-permission@afd24018f6 (2026-08-21). Data as JSON: /api/errors/7c13a93a3cc1884b. Report an issue: GitHub.