laravel/framework · error · InvalidArgumentException

Auth guard [ ] is not defined.

Error message

Auth guard [{$name}] is not defined.

What it means

Thrown by AuthManager::resolve() when getConfig($name) returns null — i.e. no guard entry exists in config/auth.php under 'guards' for the requested name. The manager looks up the guard's configuration array before attempting to build a driver, so a missing key is treated as an undefined guard.

Solutions

1. Add the guard to config/auth.php under 'guards' with a driver and provider, e.g. 'api' => ['driver' => 'sanctum'|'token'|'session', 'provider' => 'users'].
2. Correct the route middleware / Auth::guard() name to match an existing guard key.
3. Set 'defaults.guard' to a guard that actually exists in the 'guards' map.
4. Clear the config cache: php artisan config:clear, then re-cache if needed.
5. Verify the AUTH_GUARD environment variable matches a declared guard.

Example fix

// before — middleware references an undeclared guard
Route::middleware('auth:portal')->group(...);
// config/auth.php 'guards' => ['web' => [...], 'api' => [...]]

// after — declare the guard
// config/auth.php
'guards' => [
    'web' => ['driver' => 'session', 'provider' => 'users'],
    'api' => ['driver' => 'sanctum', 'provider' => 'users'],
    'portal' => ['driver' => 'session', 'provider' => 'members'],
],

// PHP — confirm a guard exists before resolving
$name = $request->route()?->middleware() ? \Str::between(last(array_filter($request->route()->middleware(), fn($m) => str_starts_with($m,'auth:'))), 'auth:', '') : null;
$config = config("auth.guards.{$name}");
if ($name !== null && $config === null) {
    abort(500, "Auth guard [{$name}] is not configured.");
}
$guard = Auth::guard($name);

function guardIsDefined(string $name): bool {
    return is_array(config("auth.guards.{$name}"));
}

try {
    return Auth::guard($name);
} catch (\InvalidArgumentException $e) {
    Log::error('Unknown auth guard requested', ['guard' => $name]);
    throw $e;
}

When it happens

Trigger: Requesting a guard via Auth::guard($name), Auth::shouldUse($name), or via middleware auth:$name where $name is absent from the 'guards' config map; using the default guard when 'defaults.guard' points at a non-existent guard name.

Common situations: Renaming/removing a guard in auth.php while middleware/routes still reference the old name; setting AUTH_GUARD env value that is not declared; typo in the route middleware string (e.g. auth:webb); config cache (php artisan config:cache) holding a stale auth.php after edits.

Related errors

• Auth driver [ ] for guard [ ] is not defined.
• Authentication user provider
• Password resetter [ ] is not defined.
• A driver must be specified.
• Broadcast connection

AI-assisted analysis of laravel/framework@e0f6eb3518 (2026-08-11). Data as JSON: /api/errors/976fb1007f4f4439. Report an issue: GitHub.

Appendix: source

Thrown at src/Illuminate/Auth/AuthManager.php:90

        $name = enum_value($name) ?: $this->getDefaultDriver();

        return $this->guards[$name] ??= $this->resolve($name);
    }

    /**
     * Resolve the given guard.
     *
     * @param  string  $name
     * @return \Illuminate\Contracts\Auth\Guard|\Illuminate\Contracts\Auth\StatefulGuard
     *
     * @throws \InvalidArgumentException
     */
    protected function resolve($name)
    {
        $config = $this->getConfig($name);

        if (is_null($config)) {
            throw new InvalidArgumentException("Auth guard [{$name}] is not defined.");
        }

        if (isset($this->customCreators[$config['driver']])) {
            return $this->callCustomCreator($name, $config);
        }

        $driverMethod = 'create'.ucfirst($config['driver']).'Driver';

        if (method_exists($this, $driverMethod)) {
            return $this->{$driverMethod}($name, $config);
        }

        throw new InvalidArgumentException(
            "Auth driver [{$config['driver']}] for guard [{$name}] is not defined."
        );
    }

    /**

View on GitHub (pinned to e0f6eb3518)