Corriger les erreurs 500 dans Laravel : une checklist éprouvée

Commencez par le journal

Une page « 500 Server Error » vous dit seulement que quelque chose a échoué. La raison se trouve dans les journaux. Regardez d’abord storage/logs/laravel.log (ou le fichier du jour si vous utilisez des journaux quotidiens). S’il est vide, l’erreur s’est produite avant que Laravel puisse l’enregistrer : consultez alors le journal d’erreurs du serveur web et celui de PHP-FPM ou LiteSpeed.

Ne passez pas APP_DEBUG=true sur un site en production pour voir l’erreur. Cela affiche les traces, les valeurs d’environnement et parfois des mots de passe à quiconque ouvre la page. Lisez plutôt les journaux.

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

1. Permissions

Laravel doit pouvoir écrire dans storage et bootstrap/cache. Après un envoi par FTP ou un déploiement avec un autre utilisateur, ces dossiers appartiennent souvent au mauvais compte. Le journal affiche alors « Permission denied » ou « failed to open stream ». Donnez à l’utilisateur du serveur web les droits d’écriture sur ces deux dossiers uniquement — ne rendez jamais tout le projet inscriptible.

2. Environnement et cache de configuration

Une valeur .env absente ou erronée est une cause classique : pas d’APP_KEY (« No application encryption key has been specified »), mauvais mot de passe de base de données ou pilote de cache inexistant sur le serveur. Rappelez-vous qu’après php artisan config:cache, Laravel ne lit plus .env à l’exécution et que tout appel à env() hors des fichiers de configuration renvoie null. Modifiez .env, puis reconstruisez le cache.

3. Dépendances et autoload

Un « Class not found » juste après un déploiement signifie généralement que vendor n’a pas été mis à jour ou que l’autoloader est obsolète. Lancez composer install avec --no-dev et --optimize-autoloader sur le serveur, et vérifiez que la version de PHP et les extensions du serveur correspondent à ce qu’exige composer.lock.

4. Base de données et migrations

Un nouveau code qui attend une colonne absente de la base produit des erreurs SQL comme « Unknown column » ou « Base table or view not found ». Exécutez les migrations en attente avec --force en production. Vérifiez aussi que la base de données et Redis sont joignables et n’ont pas épuisé leurs connexions.

5. Caches obsolètes et workers de files d’attente

Les routes, vues et configuration en cache de la version précédente peuvent pointer vers du code qui n’existe plus. Videz-les et reconstruisez-les à chaque déploiement. Les workers de files d’attente sont des processus longs : ils gardent l’ancien code en mémoire jusqu’à leur redémarrage, et les jobs peuvent échouer avec des erreurs qui ne correspondent plus à votre code.

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. Mémoire, délais et services externes

De gros exports, du traitement d’images ou des requêtes sans limite peuvent dépasser le memory_limit ou le max_execution_time de PHP. Déplacez les traitements lourds vers des jobs et traitez les données par lots. Les appels aux API externes doivent toujours avoir un délai maximal et une solution de repli, pour qu’un prestataire lent ne fasse pas tomber vos pages. Attention à la différence de codes : un 502 ou un 504 indique généralement PHP-FPM ou un délai de proxy, pas une exception applicative.

Éviter la prochaine

• Utilisez un seul script de déploiement qui exécute toujours les mêmes étapes dans le même ordre.
• Ajoutez un suivi des erreurs (par exemple Sentry ou Flare) pour être prévenu avant vos clients.
• Surveillez la route de santé /up fournie par Laravel, ainsi qu’une page qui interroge la base de données.
• Gardez la préproduction aussi proche que possible de la production : même version de PHP, mêmes extensions et pilotes de cache.