Troubleshooting

Run php artisan ui-kit:doctor first. It catches most of the list below and prints the fix beside each failure. The rest are here, with the message you will see.

`Vite manifest not found`

/login returns 500 and the exception names public/build/manifest.json. The assets were never built. Run npm run dev for local work or npm run build for a deploy.

`Jetstream detected (laravel/jetstream is installed).`

The installer stops before writing anything. Jetstream and the kit both register /login, /register and friends, and Jetstream's teams and API tokens are outside what the kit understands. Start from a fresh app. --force overrides the abort and is not recommended.

`Auth scaffolding detected and running non-interactively.`

The full message ends Re-run with --force to override, or remove the conflicting setup first. Aborting. A CI job ran ui-kit:install --no-interaction on an app that has Breeze or leftover auth files. Remove them with the commands under Why this kit, or pass --force if overwriting is what you want.

`Unknown modules: foo. Available: all, admin-middleware, …`

A slug in --modules= or in ui-kit:install-module is misspelled. Nothing was installed; the batch is validated before the first module runs. ui-kit:list-modules prints the valid slugs.

403 on `/admin`

Every admin route runs the middleware in config/admin.php. The fallback requires $user->is_admin to be truthy; with the admin-middleware module installed the user needs the Spatie admin role. Either way:

php artisan ui-kit:make-admin [email protected]

`route:cache` fails with a duplicate route name

The doctor's no duplicate route names check lists the names. The usual cause is a route file copied without its ui-kit:managed header and then also loaded by hand, so every route registers twice. Keep the header and let the provider load the file, or delete the header and load it yourself, not both.

Password reset and verification emails never arrive

Check the MAIL_* keys in .env. With MAIL_MAILER=log the messages are in storage/logs/laravel.log. The doctor reports mail from address configured as a skip until MAIL_FROM_ADDRESS is set to something other than the default.

`The installer couldn't patch your User model`

The installer applies App\Models\Concerns\UiKitUser to app/Models/User.php itself and reverts the edit if php -l rejects the result, which happens with a custom model location or an unusual class layout. Add it by hand:

class User extends Authenticatable
{
    use \App\Models\Concerns\UiKitUser;
}

The doctor's UiKitUser trait applied check confirms it.

`/register` returns 500: `RegisterViewResponse is not instantiable`

Fortify is registering its own view routes on top of the kit's. The installer sets 'views' => false in config/fortify.php; if the file was re-published or edited, set it again. The doctor's fortify views disabled check watches for this.

`Route [impersonate] not defined`

The impersonation partials link to routes that lab404/laravel-impersonate provides as a macro the app has to call. Add this to routes/web.php:

Route::middleware('auth')->group(fn () => Route::impersonate());

The impersonation module page has the details.

The welcome page's Dashboard button 404s

That button is stock Laravel and links to /dashboard, which nothing registers. The kit's panel is at /admin. Edit resources/views/welcome.blade.php to point there, or replace the page.

The default SidebarBadgeResolver returns an empty array. Bind your own, as shown under Customising.

The challenge only runs for users with a confirmed secret, and only the profile module gives users a way to enable one. Without it, two-factor is on in Fortify and unused, which is fine.

Something else

Open an issue on GitHub with the output of php artisan ui-kit:doctor and the exact error text. Most reports turn into a new doctor check.