spatie/laravel-permission · error

Please enable the teams setting in your configuration.

Error message

Please enable the teams setting in your configuration.

What it means

The permission:setup-teams Artisan command generates the add_teams_fields migration and the teams-enabled model setup. It refuses to run while Config::get('permission.teams') is falsy: it prints an error line ('Teams feature is disabled in your permission.php file.'), then this warning, and exits with FAILURE. Generating teams migrations while the feature flag is off would leave the schema and the configuration inconsistent, so the command aborts up front.

Source

Thrown at src/Commands/UpgradeForTeamsCommand.php:20

namespace Spatie\Permission\Commands;

use Illuminate\Console\Command;
use Illuminate\Support\Facades\Config;

class UpgradeForTeamsCommand extends Command
{
    protected $signature = 'permission:setup-teams';

    protected $description = 'Setup the teams feature by generating the associated migration.';

    protected string $migrationSuffix = 'add_teams_fields.php';

    public function handle(): int
    {
        if (! Config::get('permission.teams')) {
            $this->error('Teams feature is disabled in your permission.php file.');
            $this->warn('Please enable the teams setting in your configuration.');

            return self::FAILURE;
        }

        $this->line('');
        $this->info('The teams feature setup is going to add a migration and a model');

        $existingMigrations = $this->alreadyExistingMigrations();

        if ($existingMigrations) {
            $this->line('');

            $this->warn($this->getExistingMigrationsWarning($existingMigrations));
        }

        $this->line('');

        if (! $this->confirm('Proceed with the migration creation?', true)) {

View on GitHub (pinned to afd24018f6)

Solutions

1. Set 'teams' => true in config/permission.php and re-run php artisan permission:setup-teams
2. If config/permission.php does not exist, publish it first: php artisan vendor:publish --provider="Spatie\Permission\PermissionServiceProvider"
3. If you edited the config but the warning persists, clear the config cache: php artisan config:clear
4. If your published config reads the env var, set PERMISSION_TEAMS=true in .env and run php artisan config:clear

Example fix

// before — config/permission.php
'teams' => false,

// after
'teams' => true,
// then: php artisan config:clear && php artisan permission:setup-teams

// before running the command (script or code)
if (! config('permission.teams')) {
    throw new RuntimeException('Enable permission.teams (config/permission.php) before running permission:setup-teams.');
}
$exit = \Illuminate\Support\Facades\Artisan::call('permission:setup-teams');
if ($exit !== \Illuminate\Console\Command::SUCCESS) {
    // handle failure
}

When it happens

Trigger: Running `php artisan permission:setup-teams` before enabling teams in config/permission.php. The check reads the live config, so it also fires when the config file was never published (framework default 'teams' => false) or when a stale config cache still holds teams=false after an edit.

Common situations: vendor:publish was never run, so no config/permission.php exists and the default false applies; the developer edited config/permission.php but forgot `php artisan config:clear`, so the cached copy still says false; the project's .env sets PERMISSION_TEAMS=true but the published config hardcodes 'teams' => false instead of reading the env var.

Related errors

• Teams feature disabled, argument --team-id has no effect. Ei
• Teams feature disabled, argument --team-id has no effect. Ei
• 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/fadb75987cbf10dc. Report an issue: GitHub.