Errores HTTP 500 en PrestaShop 9: depuración segura en producción
Una respuesta HTTP 500 indica que una solicitud ha fallado, pero no explica por qué. En una tienda PrestaShop, el síntoma visible puede proceder de una excepción de módulo, un problema de plantilla, un fallo de base de datos, un error fatal de PHP, recursos agotados o algo que ocurrió antes de que PrestaShop terminara de arrancar.
La peor reacción es activar el modo de depuración completo en una tienda de producción con tráfico y dejarlo así mientras se espera a que el error reaparezca. La salida de depuración puede revelar rutas de archivos, trazas de llamadas y otros detalles de implementación a visitantes reales, y un fallo intermitente puede desaparecer antes de que alguien vea el mensaje útil.
Un flujo mejor mantiene la tienda en modo de producción normal, recoge suficiente contexto para identificar la solicitud que falla y utiliza pruebas del servidor o de la aplicación para acotar la causa. Esta guía muestra una forma práctica de hacerlo en PrestaShop 9.
1. Trate HTTP 500 como un síntoma, no como un diagnóstico
Empiece describiendo exactamente dónde aparece el fallo. Una caída de toda la tienda es distinta de una página de producto que solo falla con una combinación concreta, y una excepción del panel de administración después de guardar un producto es distinta de un fallo de compra en la tienda.
Registre:
- la URL o ruta exacta;
- si el fallo afecta a la tienda, al panel de administración o a una solicitud de API;
- la hora aproximada;
- la acción inmediatamente anterior al error;
- si la solicitud falla siempre o solo ocasionalmente;
- si el problema empezó después de una actualización de módulo, tema, PHP o PrestaShop;
- si solo afecta a una tienda en una instalación multitienda.
Este contexto reduce el ámbito de búsqueda antes de modificar la configuración.
2. No utilice el modo de depuración de producción como sistema de supervisión
El modo de depuración de PrestaShop resulta útil durante el desarrollo controlado y las pruebas en preproducción porque muestra las excepciones de inmediato. No sustituye a la captura de errores en producción.
En una tienda activa, dejar la depuración habilitada puede cambiar lo que ven los clientes y revelar información técnica. Tampoco resuelve los fallos intermitentes: si el error aparece una vez a las 03:00 y nadie está mirando, las pruebas útiles pueden perderse igualmente.
Utilice la depuración completa cuando pueda reproducir el problema de forma segura en preproducción o durante una ventana de mantenimiento controlada. Para el funcionamiento habitual en producción, prefiera los registros y una captura diagnóstica que sea segura incluso cuando se produzcan fallos.
3. Determine si PrestaShop tuvo tiempo de gestionar la solicitud
La primera distinción importante es si el fallo ocurrió dentro de la aplicación PrestaShop/PHP en ejecución o antes de que ese entorno estuviera disponible.
Los diagnósticos de aplicación suelen ayudar con fallos como:
- excepciones de Symfony;
- excepciones de controladores o módulos;
- excepciones de plantillas;
- excepciones de base de datos que se propagan por la aplicación;
- errores fatales de PHP que ocurren después de registrar el entorno de ejecución pertinente y los manejadores de cierre.
Pueden no detectar fallos causados por el servidor web, la terminación TLS, una caída abrupta de PHP-FPM, la terminación de un proceso por falta de memoria del sistema operativo, un proxy inverso o un proceso que muere antes de iniciar la aplicación.
Si no existe un incidente de aplicación a la hora de una respuesta 500 conocida, no suponga que la herramienta de captura falló. Compruebe el registro de errores del servidor web, el de PHP-FPM y el panel del alojamiento para la misma marca de tiempo.
4. Capture el contexto de la solicitud antes de probar correcciones al azar
Un incidente útil debe responder a más que «PHP ha fallado». Reúna suficiente información para vincular el fallo con una solicitud real:
- tipo de excepción o error;
- mensaje sin datos sensibles;
- archivo y línea;
- traza de llamadas segura;
- ruta y controlador;
- contexto de la solicitud;
- ID de tienda cuando esté disponible;
- versiones de PrestaShop y PHP;
- contexto de tema y módulos cuando esté disponible;
- uso de memoria y tiempo de ejecución cuando estén disponibles.
No recopile contraseñas, cabeceras de autorización, cookies ni cuerpos de solicitud sin procesar solo porque sean técnicamente accesibles. Los diagnósticos de producción deben ser útiles sin convertirse en un segundo almacén de datos sensibles de clientes.
5. Distinga un incidente aislado de un problema recurrente
Un fallo aislado puede deberse a una dependencia transitoria o a una solicitud inusual. Un fallo repetido con la misma firma estable merece otra prioridad.
Agrupe los incidentes repetidos por características estables, como la clase de error, el mensaje normalizado, el archivo y un marco de llamada útil. Después, controle con qué frecuencia aparece el mismo fallo y cuándo se vio por primera y última vez.
Esto convierte un flujo ruidoso de errores individuales en preguntas sobre las que puede actuar:
- ¿Este error ocurrió una vez o 500 veces?
- ¿Empezó inmediatamente después de un despliegue?
- ¿Afecta a una sola ruta?
- ¿Aparece solo en una tienda?
- ¿El mismo error sigue ocurriendo después de una corrección?
6. Reproduzca el fallo solo cuando disponga de pruebas
Cuando tenga el mensaje, la ubicación y el contexto de la solicitud, intente reproducir el fallo en el entorno más seguro disponible.
Si el incidente apunta a una página de producto, reproduzca con el mismo producto y la combinación pertinente. Si apunta a una acción de guardado administrativo, use el mismo flujo del panel de administración. Si aparece durante la compra, reproduzca con un cliente de prueba y una vía de pago de prueba aprobada, en lugar de experimentar con un pedido real.
Para errores relacionados con actualizaciones, compare el flujo que falla con el proceso de preproducción descrito en nuestra guía de actualización de PrestaShop 8 a 9.
7. Lea el primer marco útil, no solo la página final de la excepción
Una traza de llamadas resulta más útil si se lee como una secuencia de llamadas, no como un muro de rutas de archivos. Symfony puede generar la excepción de nivel superior mientras el primer marco específico del proyecto apunta a un servicio de módulo, una plantilla o una sobrescritura personalizada que intervino antes.
Busque:
- un directorio o espacio de nombres de módulo;
- una plantilla del tema implicada en el renderizado;
- una consulta de base de datos o llamada al repositorio cercana al fallo;
- una acción de controlador que acote el flujo afectado;
- un recorrido de código reciente introducido por una actualización.
No culpe automáticamente al primer nombre de archivo de terceros que vea. Las llamadas del framework y de los módulos pueden aparecer en la misma traza aunque la causa subyacente sea un dato no válido o una dependencia que falla.
8. Utilice Crash Snapshot Lite para obtener pruebas de aplicación de forma segura en producción
Crash Snapshot Lite es el módulo gratuito de PrestaSuite creado para este flujo concreto de producción. Está diseñado para capturar fallos compatibles de la aplicación PrestaShop/PHP mientras la tienda permanece en modo normal.
Su flujo Lite incluye captura de excepciones, captura de errores fatales y de cierre después del registro del entorno de ejecución, códigos de incidente, mensajes y trazas sin datos sensibles, contexto básico del entorno, agrupación por huella, recuentos de ocurrencias y un panel de incidentes.
Los incidentes fatales o de cierre utilizan una cola privada en disco para que el módulo no dependa de una conexión sana a la base de datos en el instante exacto del error fatal. Un cron privado de mantenimiento puede importar las entradas pendientes y ejecutar la limpieza según la política de conservación.
Crash Snapshot Lite funciona deliberadamente a nivel de aplicación. No puede sustituir los registros del servidor y de PHP-FPM para fallos anteriores a PrestaShop o ajenos al proceso PHP.
Consulte la documentación de PrestaSuite para obtener instrucciones de instalación, autoprueba y mantenimiento.
9. Relacione el incidente con cambios recientes sin adivinar
Si un error empieza después de un despliegue, compare los hechos antes de revertir cambios sin relación. Compare la marca de tiempo de la primera ocurrencia con:
- actualizaciones de módulos;
- actualizaciones del tema;
- actualizaciones de PrestaShop;
- cambios de versión de PHP;
- cambios en el esquema de la base de datos;
- cambios de configuración;
- nuevas tareas cron o de importación.
Una coincidencia temporal es una prueba útil, pero no concluyente. Confirme el cambio sospechoso reproduciendo la vía que falla o probando una reversión segura en preproducción.
10. Mantenga una estrategia diagnóstica de producción con dos capas
Ninguna herramienta detecta todos los fallos. Una configuración práctica de PrestaShop en producción conserva dos capas de pruebas:
- diagnósticos de aplicación para excepciones, errores fatales, rutas e incidentes agrupados;
- registros del servidor y del entorno de ejecución para fallos anteriores al arranque de la aplicación, respuestas 502/503 de sistemas previos, caídas de PHP-FPM, terminaciones por falta de recursos y eventos de infraestructura.
Esta distinción evita perder tiempo. Si la aplicación capturó el incidente, investigue primero sus pruebas. Si la solicitud falló pero no existía un entorno de ejecución de la aplicación, pase directamente a la capa del servidor.
Lista de comprobación de HTTP 500 en producción
- Mantenga desactivado el modo de depuración en producción.
- Registre la ruta exacta, la marca de tiempo y la acción del usuario.
- Compruebe si el fallo es reproducible.
- Revise los incidentes de aplicación.
- Compruebe los registros del servidor/PHP si no existe un incidente de aplicación.
- Agrupe los fallos repetidos en vez de tratar cada ocurrencia como única.
- Reproduzca en preproducción con el mismo flujo.
- Repita las pruebas después de la corrección y verifique que no haya nuevas ocurrencias.
Preguntas frecuentes
¿Debo activar la depuración cuando un cliente comunica un error 500?
No como primera respuesta en producción. Recopile primero la marca de tiempo, la ruta y los registros disponibles o el incidente capturado. Use la depuración durante una reproducción controlada cuando sea seguro mostrar la salida diagnóstica.
¿Puede un módulo PrestaShop capturar todos los HTTP 500?
No. La captura de aplicación solo funciona cuando ya existe el entorno de ejecución pertinente de PHP y PrestaShop. Los fallos del servidor web, las caídas abruptas de procesos y los fallos de infraestructura requieren registros del servidor.
¿Por qué el mismo error puede aparecer solo ocasionalmente?
Los datos desencadenantes, la ruta, el estado del cliente, la combinación, el estado de caché, una tarea en segundo plano o el nivel de recursos pueden variar entre solicitudes. Por eso, el contexto de la solicitud y el historial agrupado de ocurrencias son más útiles que una sola captura de pantalla.
¿Qué debo comprobar después de corregir el error?
Repita el flujo original, vigile nuevas ocurrencias de la misma huella y revise los registros pertinentes del servidor. Una corrección resulta más convincente cuando la vía que fallaba funciona y el incidente deja de repetirse.