Troubleshooting

Work through the log first: storage/logs/laravel.log.

Blank page / 500

1. Set APP_DEBUG=true temporarily on a staging copy (never leave it on in production).
2. Confirm PHP 8.1+ and required extensions (php -m).
3. composer install --no-dev if vendor/ is incomplete.
4. Permissions: storage/ and bootstrap/cache/ writable by PHP.
5. php artisan optimize:clear.

Mixed content or wrong links

APP_URL must be https://your-domain with no trailing path mismatch. Recache config. License activation uses the same URL.

Installer Inertia error

/install falls back to Blade if the Vue page throws. Missing public/js/app.js or a PHP exception in ModernInstallerController are common causes.

Migrations fail

Import MySQL 5.7+ / MariaDB. If you upgraded from CardGen, back up first, then php artisan migrate. Duplicate-table errors mean an older schema — restore backup and migrate cleanly.

Queue jobs stuck

Table jobs growing, no mail: cron is not running queue:work --stop-when-empty. See Queues. Failed jobs: php artisan queue:failed.

QR / images not generating

Need gd (and often exif). Check extension_loaded('gd'). Disk full or unwritable public/images/card also breaks QR SVG/PNG writes.

CSV import errors

Use the sample header in /files/card.csv. Excel files go through Maatwebsite Excel; save as CSV UTF-8 if columns look garbled.

Print layout wrong

Use the browser print dialog’s landscape/portrait to match the template. Disable “headers and footers” in the print dialog. Download PNG if the printer driver scales poorly.

Session / login loops

SESSION_DRIVER=file, writable storage/framework/sessions. Cookie name profilesuite_session. HTTPS sites need the app served as HTTPS so cookies stay secure.

Demo cannot be edited

APP_DEMO=true returns an error on global settings save. Turn it off.

After upgrade, old URLs

/t0 still redirects. Bookmarks to removed CardGen modules (contacts, notes, subscriptions) will 404 by design — see changelog.