Troubleshooting
Fixes for blank pages, stuck queues, and upgrade surprises.
Start here when local installs fail or production behaves differently from staging.
Common issues
Welcome page shows a blank screen
Clear caches with php atlas optimize:clear, confirm APP_CHANNEL matches your installed major, and rebuild the frontend assets.
Jobs never leave the queue
Ensure Redis is reachable and QUEUE_CONNECTION=redis. Sync drivers hide race conditions that appear only under load.
Class not found after upgrade
Run composer dump-autoload and php atlas package:discover after upgrading. Stale classmaps are common after major bumps.
Danger
If you are mid-upgrade, finish the migration checklist before chasing unrelated bugs. Mixed 2.x/3.x binaries produce misleading errors.
- Capture the request_id or stack trace
- Note the installed atlas/framework version
- Confirm which documentation channel you followed
Updated Aug 5, 2026