500-Fehler in Laravel beheben – eine bewährte Checkliste

Von Dateirechten im Storage bis zu Queue-Workern: genau die Reihenfolge, die wir abarbeiten, wenn eine Laravel-App ausfällt.

Mit dem Log anfangen

Eine „500 Server Error“-Seite sagt nur, dass etwas fehlgeschlagen ist. Der Grund steht in den Logs. Schau zuerst in storage/logs/laravel.log (oder die Tagesdatei bei täglichen Logs). Ist sie leer, trat der Fehler auf, bevor Laravel ihn protokollieren konnte – prüfe dann das Fehlerlog des Webservers und das von PHP-FPM oder LiteSpeed.

Setze auf einer Live-Website nicht APP_DEBUG=true, um den Fehler zu sehen. Das zeigt jedem Besucher Stacktraces, Umgebungswerte und manchmal Passwörter. Lies stattdessen die 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. Berechtigungen

Laravel muss in storage und bootstrap/cache schreiben können. Nach einem FTP-Upload oder einem Deployment mit anderem Benutzer gehören diese Ordner oft dem falschen Konto. Das Log zeigt dann „Permission denied“ oder „failed to open stream“. Gib dem Webserver-Benutzer Schreibrechte nur auf diese beiden Ordner – mach nie das ganze Projekt beschreibbar.

2. Umgebung und Konfigurations-Cache

Ein fehlender oder falscher .env-Wert ist ein Klassiker: kein APP_KEY („No application encryption key has been specified“), falsches Datenbankpasswort oder ein Cache-Treiber, den es auf dem Server nicht gibt. Denk daran: Nach php artisan config:cache liest Laravel .env zur Laufzeit nicht mehr, und jeder env()-Aufruf außerhalb der Konfigurationsdateien liefert null. Ändere .env und baue den Cache neu.

3. Abhängigkeiten und Autoloading

„Class not found“ direkt nach einem Deployment bedeutet meist, dass vendor nicht aktualisiert wurde oder der Autoloader veraltet ist. Führe composer install mit --no-dev und --optimize-autoloader auf dem Server aus und prüfe, ob PHP-Version und Erweiterungen des Servers zu composer.lock passen.

4. Datenbank und Migrationen

Neuer Code, der eine Spalte erwartet, die die Datenbank noch nicht hat, erzeugt SQL-Fehler wie „Unknown column“ oder „Base table or view not found“. Führe ausstehende Migrationen in Produktion mit --force aus. Prüfe auch, ob Datenbank und Redis erreichbar sind und keine Verbindungen mehr frei haben.

5. Veraltete Caches und Queue-Worker

Gecachte Routen, Views und Konfiguration aus dem vorherigen Release können auf Code verweisen, den es nicht mehr gibt. Leere und baue sie bei jedem Deployment neu. Queue-Worker sind lang laufende Prozesse: Sie behalten den alten Code im Speicher, bis sie neu starten, und Jobs können mit Fehlern scheitern, die nicht mehr zu deinem 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. Speicher, Timeouts und externe Dienste

Große Exporte, Bildverarbeitung oder unbegrenzte Abfragen können PHPs memory_limit oder max_execution_time überschreiten. Verlagere schwere Arbeit in Queue-Jobs und verarbeite Daten in Blöcken. Aufrufe externer APIs brauchen immer einen Timeout und einen Fallback, damit ein langsamer Anbieter deine Seiten nicht lahmlegt. Achte auf den Unterschied der Codes: Ein 502 oder 504 deutet meist auf PHP-FPM oder einen Proxy-Timeout hin, nicht auf eine Exception der Anwendung.

Den nächsten verhindern

Nutze ein einziges Deploy-Skript, das immer dieselben Schritte in derselben Reihenfolge ausführt.
Richte Error-Tracking ein (zum Beispiel Sentry oder Flare), damit du Fehler vor deinen Kunden bemerkst.
Überwache die Health-Route /up, die Laravel mitbringt, und zusätzlich eine Seite, die die Datenbank abfragt.
Halte Staging so nah wie möglich an Produktion: gleiche PHP-Version, Erweiterungen und Cache-Treiber.