Laravel Jetstream Livewire 2FA Not Prompting or QR Fails – Diagnostic Guide

Recognizable condition

A user enables two-factor authentication in the Jetstream Livewire profile screen, but subsequent logins skip the OTP challenge, the QR code does not render in the enrollment modal, or submitted codes are consistently rejected as invalid.

This guide assumes Laravel 9+ with Jetstream 2.x Livewire stack and Fortify for authentication. Steps differ for Inertia or React/Vue stacks.

Cause / diagnostic table

Symptom	Likely cause
2FA toggle missing or OTP step skipped on login	`two_factor` feature not enabled in Jetstream configuration
QR code does not render	Livewire component error or missing QR code generation dependency required by the installed Jetstream version
OTP verification always fails after enrollment	Missing `two_factor_secret` / `two_factor_recovery_codes` columns, or `APP_KEY` changed after enrollment
Challenge state lost between requests	Session or cache driver not persistent, e.g., `array` driver in a production-like flow

Ordered checks

1. Verify feature flag. Open config/jetstream.php. Confirm the features array includes 'two_factor' for the Livewire stack. Clear config cache after changes: php artisan config:cache. Note: Fortify configuration is used by Jetstream internally; check version-specific documentation for any additional feature toggles.
2. Check database schema. Run php artisan migrate:status where to run: project root with appropriate permissions. Inspect the users table for columns two_factor_secret and two_factor_recovery_codes. Absence indicates missing Jetstream migrations.
3. Validate application key and persistence. Confirm APP_KEY is set in .env and has not been rotated since users enrolled. Two-factor secrets are encrypted with the app key; rotation invalidates existing secrets. Verify SESSION_DRIVER and CACHE_DRIVER are persistent in the environment being tested, not array.
4. Test enrollment rendering. In an incognito browser, enable 2FA on a test account. Observe whether the QR code element appears and whether the recovery codes are displayed. Open browser developer tools for Livewire JavaScript errors and check storage/logs/laravel.log for exceptions during the request.

Fixes tied to findings

• If the feature flag is missing, add 'two_factor' to the features array in config/jetstream.php and clear config cache.
• If columns are missing, publish Jetstream migrations and run php artisan migrate. Do not enable 2FA without recovery codes being generated and stored.
• If APP_KEY was rotated, restore the original key or plan re-enrollment for affected users. Re-enrollment is required because encrypted secrets cannot be recovered after key change.
• If session/cache is non-persistent, change to a persistent driver such as file, redis, or database and clear caches: php artisan cache:clear.
• If QR code does not render, verify the QR code generation dependency required by your Jetstream version is installed and frontend assets are built. Dependency names vary by version; consult the version-specific Jetstream documentation rather than assuming a package.

Escalation criteria

• Configuration, migrations, APP_KEY, and drivers are correct but the challenge still does not appear or verification fails.
• Capture browser console Livewire errors and storage/logs/laravel.log entries from a test enrollment and login attempt.
• Provide a minimal reproduction with Laravel, Jetstream, PHP versions and relevant config snippets before contacting support or filing a bug.