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:assign-role command accepts a --team-id option, but that option is only meaningful when the teams feature is on (PermissionRegistrar::$teams, driven by config('permission.teams')). When teams is disabled and --team-id is passed, the command prints this warning and returns SUCCESS immediately — no role is assigned at all. The early return prevents an assignment that would silently ignore the team scope the caller asked for.

Source

Thrown at src/Commands/AssignRoleCommand.php:29

{
    protected $signature = 'permission:assign-role
        {name : The name of the role}
        {userId : The ID of the user to assign the role to}
        {guard? : The name of the guard}
        {userModelNamespace=App\Models\User : The fully qualified class name of the user model}
        {--team-id=}';

    protected $description = 'Assign a role to a user';

    public function handle(PermissionRegistrar $permissionRegistrar): int
    {
        $roleName = $this->argument('name');
        $userId = $this->argument('userId');
        $guardName = $this->argument('guard');
        $userModelClass = $this->argument('userModelNamespace');

        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;
        }

        // Validate that the model class exists and is instantiable
        if (! class_exists($userModelClass)) {
            $this->error("User model class [{$userModelClass}] does not exist.");

            return self::FAILURE;
        }

        $user = (new $userModelClass)::find($userId);

        if (! $user) {
            $this->error("User with ID {$userId} not found.");

            return self::FAILURE;
        }

View on GitHub (pinned to afd24018f6)

Solutions

1. Remove the --team-id option: php artisan permission:assign-role writer 1 web App\Models\User
2. If the assignment genuinely needs team scoping, enable teams first: set 'teams' => true in config/permission.php, run php artisan permission:setup-teams, migrate, then re-run the command with --team-id
3. Verify the effective flag with `php artisan tinker` → config('permission.teams'), and run php artisan config:clear after any config edit

Example fix

# before
php artisan permission:assign-role writer 1 web App\Models\User --team-id=2
# exits 0 with the warning and assigns nothing

# after (single-tenant app)
php artisan permission:assign-role writer 1 web App\Models\User

// build the command call without a dead --team-id option
$teamsEnabled = app(\Spatie\Permission\PermissionRegistrar::class)->teams;
$args = [
    'name' => 'writer',
    'userId' => $user->id,
    'guard' => 'web',
    'userModelNamespace' => $user::class,
];
$options = ($teamsEnabled && $teamId) ? ['--team-id' => $teamId] : [];
\Illuminate\Support\Facades\Artisan::call('permission:assign-role', $args + $options);

When it happens

Trigger: Running `php artisan permission:assign-role <name> <userId> <guard> <userModelNamespace> --team-id=X` while config('permission.teams') is false. The check is `$permissionRegistrar->teams && $this->option('team-id')`: any truthy --team-id value with the feature off triggers it.

Common situations: Copy-pasting a team-scoped command from a multi-tenant project into a single-tenant app; teams enabled in staging but disabled in production (or vice versa) so the same deploy script behaves differently; a leftover --team-id flag in a provisioning script after the teams feature was removed.

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/c1832b96db8805d4. Report an issue: GitHub.