Cómo resolver errores 500 en Laravel: una lista de comprobación probada

Empieza por el log

Una página de “500 Server Error” solo te dice que algo ha fallado. La razón está en los logs. Mira primero storage/logs/laravel.log (o el fichero diario si usas logs diarios). Si está vacío, el error ocurrió antes de que Laravel pudiera registrarlo, así que revisa después el log de errores del servidor web y el de PHP-FPM o LiteSpeed.

No pongas APP_DEBUG=true en un sitio en producción para ver el error. Muestra trazas, valores del entorno y a veces contraseñas a cualquiera que abra la página. Lee los 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. Permisos

Laravel necesita poder escribir en storage y bootstrap/cache. Tras subir ficheros por FTP o desplegar con otro usuario, estas carpetas suelen pertenecer a la cuenta equivocada. El log mostrará “Permission denied” o “failed to open stream”. Da permiso de escritura al usuario del servidor web solo en esas dos carpetas; nunca hagas escribible todo el proyecto.

2. Entorno y caché de configuración

Un valor de .env que falta o es incorrecto es una causa clásica: sin APP_KEY (“No application encryption key has been specified”), contraseña de base de datos errónea o un driver de caché que no existe en el servidor. Recuerda que tras php artisan config:cache, Laravel ya no lee .env en tiempo de ejecución y cualquier llamada a env() fuera de los ficheros de configuración devuelve null. Cambia .env y vuelve a generar la caché.

3. Dependencias y autoload

Un “Class not found” justo después de desplegar suele significar que vendor no se actualizó o que el autoloader está obsoleto. Ejecuta composer install con --no-dev y --optimize-autoloader en el servidor, y comprueba que la versión de PHP y las extensiones del servidor coinciden con lo que exige composer.lock.

4. Base de datos y migraciones

Un código nuevo que espera una columna que la base de datos aún no tiene produce errores SQL como “Unknown column” o “Base table or view not found”. Ejecuta las migraciones pendientes con --force en producción. Comprueba también que la base de datos y Redis son accesibles y no se han quedado sin conexiones.

5. Cachés obsoletas y workers de colas

Las rutas, vistas y configuración cacheadas de la versión anterior pueden apuntar a código que ya no existe. Límpialas y regenéralas en cada despliegue. Los workers de colas son procesos de larga duración: mantienen el código antiguo en memoria hasta que se reinician, así que los jobs pueden fallar con errores que ya no corresponden a tu código.

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. Memoria, tiempos límite y servicios externos

Exportaciones grandes, procesamiento de imágenes o consultas sin límite pueden superar el memory_limit o el max_execution_time de PHP. Lleva el trabajo pesado a jobs en cola y procesa los datos por lotes. Las llamadas a APIs externas deben tener siempre un tiempo límite y una alternativa, para que un proveedor lento no tumbe tus páginas. Ojo a la diferencia de códigos: un 502 o 504 suele apuntar a PHP-FPM o a un tiempo límite del proxy, no a una excepción de la aplicación.

Evita el siguiente

• Usa un único script de despliegue que ejecute siempre los mismos pasos en el mismo orden.
• Añade seguimiento de errores (por ejemplo Sentry o Flare) para enterarte antes que tus clientes.
• Monitoriza la ruta de salud /up que incluye Laravel, además de una página que consulte la base de datos.
• Mantén staging lo más parecido posible a producción: misma versión de PHP, extensiones y drivers de caché.