Troubleshooting
A practical symptom → fix guide for node operators.
The site won't load
| Symptom |
Likely fix |
| Blank page / HTTP 500 after upload |
composer install didn't finish; vendor/ missing; .env has no APP_KEY; storage/ not writable. Run composer install --no-dev --prefer-dist, php artisan key:generate, fix permissions |
| "No input file specified" |
Document root isn't pointing at public/ (or the shared-hosting .htaccess is missing) |
404 on /robots.txt, /css/, /js/ |
App-root docroot without the shared-hosting .htaccess — copy deploy/shared-hosting-webroot.htaccess to the app root |
| Login loop on HTTPS |
Set SESSION_SECURE_COOKIE=true (+ SESSION_ENCRYPT=true) |
| 406 on form POSTs (curl/scripts only) |
Host WAF (ModSecurity) rejecting requests without browser headers — real browsers are fine |
HTTPS / certificates
| Symptom |
Likely fix |
| Cert stays self-signed on cPanel |
The domain + www are excluded from AutoSSL by default. cPanel → SSL/TLS Status → remove from exclusions → Run AutoSSL |
| Cert not renewing |
Let's Encrypt 90-day validity — check AutoSSL ran; DNS must resolve to the server |
Email
| Symptom |
Likely fix |
| Verification emails never arrive |
MAIL_MAILER still log, or SMTP misconfigured — see Email / SMTP |
550 from mail server |
Bad credentials, or sending to an address the server rejects |
| TLS CN mismatch |
MAIL_HOST must be the server hostname, not 127.0.0.1 |
Federation
| Symptom |
Likely fix |
| Inbound posts never appear |
Confirm fedifuel:consume-inbound runs in cron and check storage/logs/laravel.log |
| WebFinger 404 |
FEDERATION_PUBLIC_BASE_URL not your real domain, or driver mismatch |
| FediFuel not connecting |
Settings → Federation → Test connection; check URL + API key |
| No federation activity on dashboard |
Check social_federation_messages is being written; ensure cron/worker runs |
Queues & workers
| Symptom |
Likely fix |
| Pending federation growing |
Queue worker not draining — confirm cron queue:work database --stop-when-empty runs |
| Jobs stuck |
Restart the worker; check failed_jobs table |
| No persistent worker available |
Database queue + cron is the shared-hosting pattern — see Configuration |
Admin panel
| Symptom |
Likely fix |
Can't enter /admin |
Need the super_admin role, or an allowlisted admin_emails entry |
| Users list empty |
Only the admin exists so far (or filter is on Pending) — not a bug |
| Settings page 500 on save |
Outdated code — pull the latest (nullable settings fix) and re-run optimize:clear |
Media
| Symptom |
Likely fix |
| Uploads fail on cloud disk |
Credentials empty in Settings → Media Storage or .env — use Test connection |
| Old media URLs 404 after switch |
Files stay where they were; migrate manually (see Media storage) |
General debug loop
tail -f storage/logs/laravel.log
php artisan config:clear after any .env change
php artisan optimize:clear after pulling code
php artisan migrate:status — everything should say Ran
- Check the host's PHP error log (e.g. cPanel
~/logs/php.error.log)
Data safety
- Never run
migrate:fresh / db:wipe on a live node with real members.
- Back up the database before any migration that could touch existing rows.
- Additive migrations are the project policy; if you believe one will lose
data, stop and investigate before running it.
Related