500-fouten in Laravel oplossen — een beproefde checklist

Van opslagrechten tot queue workers: dit is precies de volgorde die we doorlopen als een Laravel-app plat ligt.

Begin bij het log

Een pagina met “500 Server Error” vertelt je alleen dat er iets misging. De reden staat in de logs. Kijk eerst in storage/logs/laravel.log (of het dagbestand als je daily logs gebruikt). Is dat leeg, dan ging het mis voordat Laravel het kon loggen; controleer dan het foutenlog van de webserver en daarna het foutenlog van PHP-FPM of LiteSpeed.

Zet APP_DEBUG=true niet aan op een live site om de fout te zien. Dan toon je stack traces, omgevingswaarden en soms wachtwoorden aan iedereen die de pagina opent. Lees in plaats daarvan de logs.

tail -n 100 storage/logs/laravel.log
# no entries? check the server logs, for example:
tail -n 100 /var/log/nginx/error.log

1. Rechten

Laravel moet kunnen schrijven naar storage en bootstrap/cache. Na een upload via FTP of een deploy als een andere gebruiker zijn deze mappen vaak eigendom van het verkeerde account. Het log toont dan “Permission denied” of “failed to open stream”. Geef de gebruiker van de webserver alleen schrijfrechten op die twee mappen — maak nooit het hele project beschrijfbaar.

2. Omgeving en configuratiecache

Een ontbrekende of verkeerde waarde in .env is een klassieke oorzaak: geen APP_KEY (“No application encryption key has been specified”), een verkeerd databasewachtwoord of een cachedriver die op de server niet bestaat. Let op: na php artisan config:cache leest Laravel .env niet meer tijdens runtime, en elke env()-aanroep buiten configuratiebestanden geeft null terug. Pas .env aan en bouw daarna de cache opnieuw op.

3. Dependencies en autoloading

“Class not found” direct na een deploy betekent meestal dat vendor niet is bijgewerkt of dat de autoloader verouderd is. Draai composer install met --no-dev en --optimize-autoloader op de server, en controleer of de PHP-versie en extensies van de server overeenkomen met wat composer.lock vereist.

4. Database en migraties

Nieuwe code die een kolom verwacht die de database nog niet heeft, geeft SQL-fouten zoals “Unknown column” of “Base table or view not found”. Draai openstaande migraties in productie met --force. Controleer ook of de database en Redis bereikbaar zijn en niet door hun verbindingen heen zijn.

5. Verouderde caches en queue workers

Gecachte routes, views en configuratie van de vorige release kunnen verwijzen naar code die niet meer bestaat. Leeg ze en bouw ze opnieuw op bij elke deploy. Queue workers zijn langlopende processen: ze houden de oude code in het geheugen tot ze herstarten, waardoor jobs kunnen falen met fouten die niet meer bij je code passen.

composer install --no-dev --optimize-autoloader
php artisan migrate --force
php artisan optimize:clear
php artisan config:cache && php artisan route:cache && php artisan view:cache
php artisan queue:restart

6. Geheugen, timeouts en externe diensten

Grote exports, beeldbewerking of onbegrensde query's kunnen de memory_limit of max_execution_time van PHP overschrijden. Verplaats zwaar werk naar jobs in de queue en verwerk data in stukken. Aanroepen naar externe API's moeten altijd een timeout en een fallback hebben, zodat één trage provider je pagina's niet plat kan leggen. Let op het verschil tussen codes: een 502 of 504 wijst meestal op een timeout van PHP-FPM of een proxy, niet op een exception in de applicatie.

Voorkom de volgende

Gebruik één deployscript dat altijd dezelfde stappen in dezelfde volgorde uitvoert.
Voeg error tracking toe (bijvoorbeeld Sentry of Flare), zodat je fouten hoort voordat klanten ze melden.
Monitor de health-route /up die Laravel meelevert, plus een pagina die de database raakt.
Houd staging zo dicht mogelijk bij productie: dezelfde PHP-versie, extensies en cachedrivers.