PrestaShop Página en Blanco Después de Actualizar el Core: Guía de Recuperación

Por Qué Aparecen Páginas en Blanco Después de las Actualizaciones de PrestaShop

Una página blanca vacía, a menudo llamada White Screen of Death (WSOD) o pantalla blanca de la muerte, es uno de los problemas más comunes y alarmantes que enfrentan los propietarios de tiendas PrestaShop después de actualizar el software core. Inicias una actualización de la versión 1.7.8.7 a la 1.7.8.8, o de la 8.1.0 a la 8.1.5, el proceso parece completarse, y luego toda tu tienda, tanto el front office como el back office, muestra nada más que una pantalla blanca. Sin mensajes de error, sin contenido parcial, solo vacío.

Comprender por qué ocurre esto requiere entender lo que hace una actualización del core de PrestaShop. El proceso de actualización reemplaza cientos de archivos PHP, modifica tablas de la base de datos, regenera índices de clases, vacía cachés y potencialmente ejecuta consultas de migración. Cualquier fallo en cualquier punto de esta cadena puede dejar la tienda en un estado inconsistente donde PHP encuentra un error fatal pero no tiene forma de mostrarlo porque la notificación de errores está deshabilitada en modo producción.

Las causas más comunes se agrupan en varias categorías: módulos incompatibles que hacen referencia a clases core eliminadas o modificadas, incompatibilidades de versión PHP entre la versión antigua y la nueva de PrestaShop, conflictos de archivos override donde las personalizaciones colisionan con archivos core modificados, recursos de servidor insuficientes que causan que el proceso de actualización termine a mitad del proceso, y fallos de migración de base de datos que dejan las tablas en un estado inconsistente.

Paso 1: Habilitar el Modo Debug

La primera acción cuando te enfrentas a una página en blanco es hacer visibles los errores. PrestaShop suprime la salida de errores en modo producción para evitar exponer información sensible a los visitantes. Necesitas habilitar temporalmente el modo debug para ver qué está realmente fallando.

El método más rápido es editar el archivo /config/defines.inc.php. Busca la línea que define _PS_MODE_DEV_ y cámbiala:

define('_PS_MODE_DEV_', true);

Si no puedes acceder a los archivos vía FTP o SSH porque tu panel de hosting también es inaccesible, algunos proveedores de hosting ofrecen un administrador de archivos a través de su panel de control (cPanel, Plesk, DirectAdmin) que opera independientemente de tu instalación de PrestaShop.

En PrestaShop 8.x, también puedes habilitar el modo debug a través del archivo .env en el directorio raíz. Cambia APP_ENV=prod a APP_ENV=dev y establece APP_DEBUG=1. Esto activa la barra de herramientas de depuración de Symfony y las páginas de error detalladas.

Después de habilitar el modo debug, recarga la página. En lugar de una pantalla blanca, ahora deberías ver un mensaje de error detallado con una ruta de archivo, número de línea y traza de pila. Este mensaje de error es la clave para diagnosticar y resolver el problema.

Paso 2: Verificar los Registros de Errores

Si habilitar el modo debug sigue mostrando una página en blanco (lo que puede ocurrir si el error sucede antes de que PHP cargue el framework de PrestaShop), verifica directamente los registros de errores del servidor.

En servidores Apache, el registro de errores se encuentra típicamente en /var/log/apache2/error.log o /var/log/httpd/error_log. En Nginx con PHP-FPM, verifica /var/log/nginx/error.log y /var/log/php-fpm/error.log (o /var/log/php8.1-fpm.log dependiendo de tu versión de PHP). En hosting compartido, los registros de errores generalmente son accesibles a través del panel de control del hosting o en un directorio logs dentro de tu cuenta de hosting.

PrestaShop también mantiene sus propios archivos de registro en el directorio /var/logs/ (PrestaShop 1.7) o /var/log/ (PrestaShop 8.x). Busca archivos con la fecha actual. Estos registros basados en Symfony pueden contener información detallada sobre lo que salió mal durante el proceso de actualización.

Además, verifica el directorio /log/ en el directorio raíz de PrestaShop para cualquier archivo de registro de errores. Algunas versiones de PrestaShop escriben errores críticos aquí cuando no pueden mostrarlos en pantalla.

Causa Común 1: Módulos Incompatibles

Los módulos son la causa más frecuente de páginas en blanco después de las actualizaciones. Un módulo que funcionaba perfectamente en PrestaShop 1.7.8.7 puede hacer que toda la tienda se caiga en la 1.7.8.8 si utiliza clases o métodos core internos que cambiaron en la actualización.

El mensaje de error típicamente aparece como: Fatal error: Class 'NombreClase' not found o Fatal error: Call to undefined method NombreClase::nombreMetodo() o Fatal error: Declaration of ClaseModulo::hookMethod() must be compatible with ClaseCore::hookMethod().

Para solucionarlo, necesitas identificar y desactivar el módulo problemático. Si puedes acceder al back office (a veces solo el front office se cae), ve a Módulos y desactiva los módulos recientemente instalados o actualizados uno por uno hasta que el problema se resuelva.

Si el back office también es inaccesible, desactiva los módulos a través de la base de datos. Conéctate a tu base de datos usando phpMyAdmin o un cliente MySQL y ejecuta:

UPDATE ps_module SET active = 0 WHERE name = 'nombre_modulo_problematico';

Si no sabes qué módulo está causando el problema, puedes desactivar todos los módulos de terceros a la vez estableciendo su columna active en 0. Primero, identifica qué módulos son de terceros verificando el directorio /modules/ para módulos no nativos de PrestaShop. Luego desactívalos selectivamente.

Un enfoque más agresivo es renombrar el directorio del módulo. Por ejemplo, renombra /modules/algunmodulo/ a /modules/algunmodulo_desactivado/. PrestaShop no puede cargar un módulo cuyo directorio no coincide con su nombre registrado, desactivándolo efectivamente sin tocar la base de datos.

Causa Común 2: Incompatibilidad de Versión PHP

Cada versión de PrestaShop requiere un rango específico de versiones PHP. PrestaShop 1.7.6 y anteriores requieren PHP 7.1 a 7.3. PrestaShop 1.7.7 a 1.7.8 soportan PHP 7.2 a 8.0. PrestaShop 8.0 requiere PHP 7.2 a 8.1. PrestaShop 8.1 requiere PHP 8.0 a 8.2. PrestaShop 9.0 requiere PHP 8.1 o superior.

Si tu entorno de hosting cambió las versiones de PHP durante o junto con la actualización de PrestaShop, puedes encontrar errores de sintaxis o llamadas a funciones obsoletas. Los errores comunes de compatibilidad PHP incluyen: Deprecated: Function create_function() is deprecated (PHP 7.2+ con código escrito para PHP 5.x), Fatal error: Uncaught Error: Call to undefined function mysql_connect() (PHP 7.0+ eliminó la extensión mysql), y Fatal error: Array and string offset access syntax with curly braces is no longer supported (PHP 8.0+).

Verifica tu versión PHP actual mirando la salida de phpinfo() o ejecutando php -v en la línea de comandos. Si la versión está fuera del rango soportado para tu versión de PrestaShop, cambia a una versión PHP compatible a través de tu panel de control de hosting.

Causa Común 3: Conflictos de Override

El sistema de override de PrestaShop permite a módulos y desarrolladores modificar el comportamiento core colocando archivos de clase modificados en el directorio /override/. Durante una actualización, las clases core cambian, pero los archivos de override permanecen. Si un override hace referencia a una firma de método que cambió, una propiedad que fue eliminada o una clase que fue renombrada, el override causa un error fatal.

El archivo de índice de clases en /var/cache/prod/class_index.php (o /cache/class_index.php en versiones anteriores) mapea los nombres de clases a sus ubicaciones de archivo, incluyendo los overrides. Un índice de clases obsoleto o corrupto puede cargar el archivo equivocado para una clase, causando caídas inmediatas.

Para probar si los overrides son el problema, desactiva temporalmente el sistema de override. Edita /config/defines.inc.php y añade o modifica:

define('_PS_HOST_MODE_', false);

Luego elimina el archivo de índice de clases para forzar a PrestaShop a regenerarlo sin overrides. Si la tienda carga después de este cambio, el problema está en uno de tus archivos de override.

Para identificar el override problemático específico, mira en los directorios /override/classes/ y /override/controllers/. Elimina los archivos de override uno a la vez, eliminando el índice de clases después de cada eliminación, hasta que encuentres el que causa la caída. Una vez identificado, actualiza el override para que sea compatible con la nueva versión core o elimínalo completamente si ya no es necesario.

Causa Común 4: Caché y Archivos Compilados

PrestaShop genera plantillas Smarty compiladas, cachés de contenedores Symfony, mapas de clases y varios otros archivos en caché que se vuelven inválidos después de una actualización. Si el proceso de actualización no vació correctamente estas cachés, la tienda intenta usar archivos en caché que hacen referencia a la estructura de código anterior.

Vacía todas las cachés manualmente eliminando el contenido de estos directorios (elimina el contenido, no los directorios mismos):

/var/cache/prod/ y /var/cache/dev/ para la caché de Symfony. Elimina todo dentro de estos directorios. PrestaShop los regenerará en la próxima carga de página.

/cache/smarty/compile/ y /cache/smarty/cache/ para las cachés de plantillas Smarty. Las plantillas compiladas obsoletas son una causa muy común de páginas en blanco después de las actualizaciones.

/var/cache/prod/class_index.php (o /cache/class_index.php) para el mapa de clases. Este archivo debe ser regenerado después de cualquier actualización.

En configuraciones PHP-FPM, también restablece OPcache. OPcache almacena bytecode PHP compilado en memoria y puede servir el código antiguo incluso después de que los archivos hayan sido reemplazados. Reinicia el servicio PHP-FPM o, si no puedes hacerlo, crea un pequeño archivo PHP que llame a opcache_reset() y accede a él a través de tu navegador.

Causa Común 5: Fallos en la Migración de la Base de Datos

Las actualizaciones de PrestaShop a menudo incluyen cambios en el esquema de la base de datos: nuevas columnas, índices modificados, nuevas tablas o migraciones de datos. Si el proceso de actualización fue interrumpido (timeout, límite de memoria, caída de conexión), la base de datos puede estar en un estado de migración parcial.

Verifica la base de datos de PrestaShop para la tabla ps_configuration y busca el valor PS_VERSION_DB. Si este valor no coincide con la versión de los archivos en disco, la actualización no se completó correctamente. PrestaShop puede intentar re-ejecutar las migraciones en la próxima carga, o simplemente puede fallar.

Los fallos de migración de base de datos son los más difíciles de recuperar sin un respaldo. Si tienes un respaldo de la base de datos de antes de la actualización, restaurarlo y re-ejecutar la actualización es a menudo el camino más seguro. Si no tienes un respaldo, es posible que necesites aplicar manualmente los archivos de migración SQL faltantes encontrados en el directorio /install/upgrade/sql/.

Procedimiento de Recuperación Paso a Paso

Sigue esta secuencia cuando te recuperes de una página en blanco después de una actualización core. El orden importa porque cada paso o resuelve el problema o elimina una posible causa.

Paso 1: Habilita el modo debug en /config/defines.inc.php estableciendo _PS_MODE_DEV_ a true. Recarga la página y lee el mensaje de error.

Paso 2: Elimina el contenido de /var/cache/prod/, /var/cache/dev/, /cache/smarty/compile/ y /cache/smarty/cache/. Elimina class_index.php. Recarga la página.

Paso 3: Si el error apunta a un módulo específico, desactiva ese módulo renombrando su directorio o estableciendo active = 0 en la tabla de base de datos ps_module. Recarga la página.

Paso 4: Si el error apunta a un archivo de override, mueve el contenido del directorio /override/ a una ubicación de respaldo temporal. Elimina class_index.php nuevamente. Recarga la página.

Paso 5: Verifica que tu versión PHP sea compatible con la versión de PrestaShop a la que actualizaste. Verifica phpinfo() o php -v. Cambia la versión de PHP si es necesario.

Paso 6: Verifica los permisos de archivos. El proceso de actualización puede haber creado archivos con propiedad incorrecta. Todos los archivos de PrestaShop deben ser legibles por el usuario del servidor web, y los directorios /var/, /cache/, /img/, /upload/, /download/, /translations/, /themes/ y /modules/ deben ser escribibles.

Paso 7: Si ninguno de los pasos anteriores resuelve el problema y tienes un respaldo de la base de datos, restaura la base de datos y los archivos del respaldo, luego intenta la actualización nuevamente después de abordar cualquier problema que identificaste durante el diagnóstico.

Procedimiento de Actualización Seguro para Futuras Actualizaciones

La prevención es mucho mejor que la recuperación. Sigue este procedimiento para cada actualización del core de PrestaShop para minimizar el riesgo de páginas en blanco y pérdida de datos.

Antes de la actualización: Crea un respaldo completo tanto de la base de datos como de todos los archivos. No solo la base de datos, no solo los archivos, sino ambos. Almacena estos respaldos en una ubicación fuera de tu cuenta de hosting si es posible. Verifica que puedas realmente restaurar desde estos respaldos antes de proceder.

Desactiva todos los módulos de terceros. Este es el paso más efectivo que puedes tomar para prevenir páginas en blanco. Los módulos core (los que vienen con PrestaShop) están diseñados para ser compatibles con la actualización, pero los módulos de terceros no tienen garantía. Desactívalos antes de la actualización y reactívalos uno por uno después, probando la tienda después de cada reactivación.

Desactiva el sistema de override. Si tienes overrides personalizados, desactívalos antes de la actualización. Re-evalúa cada override después de la actualización para determinar si sigue siendo compatible y si todavía es necesario.

Revisa las notas de la versión. Cada lanzamiento de PrestaShop incluye notas sobre requisitos de compatibilidad, problemas conocidos y cambios que rompen compatibilidad. Léelas antes de actualizar, no después de que algo se rompa.

Pon la tienda en modo mantenimiento. Esto evita que los clientes hagan pedidos durante la actualización y encuentren errores. Navega a Parámetros de la Tienda, General, Mantenimiento en el back office y habilita el modo mantenimiento.

Durante la actualización: Monitorea el proceso de actualización. No cierres la pestaña del navegador ni navegues a otro lugar. Si la actualización tarda más de lo esperado, verifica los registros de errores del servidor para errores de timeout o memoria. Si el proceso parece atascado, espera al menos 10 minutos antes de tomar cualquier acción, ya que las tiendas grandes pueden tener migraciones de base de datos significativas que procesar.

Después de la actualización: Vacía todas las cachés. Verifica que el back office carga correctamente. Verifica el front office. Reactiva los módulos uno por uno, verificando la tienda después de cada uno. Reactiva los overrides uno por uno si aplica. Desactiva el modo mantenimiento. Monitorea los registros de errores durante las siguientes 24 horas.

Estrategias de Rollback

Cuando la recuperación no es posible o consume demasiado tiempo, volver a la versión anterior puede ser la mejor opción. Sin embargo, PrestaShop no tiene un mecanismo de rollback integrado, por lo que necesitas planificar esta posibilidad antes de iniciar la actualización.

Rollback completo desde respaldo: Restaura tanto la base de datos como los archivos desde tu respaldo pre-actualización. Este es el enfoque más limpio pero requiere que hayas hecho un respaldo completo antes de la actualización. Después de restaurar, verifica que la tienda funcione correctamente y que ningún pedido o dato de cliente creado durante el período de actualización fallida se haya perdido (si la tienda estaba en modo mantenimiento, nada debería haber cambiado).

Rollback parcial de archivos: Si solo los archivos están corruptos pero la base de datos está bien, puedes reemplazar los archivos de PrestaShop con la versión anterior manteniendo la base de datos actual. Descarga la versión anterior exacta de PrestaShop del archivo oficial de lanzamientos, extráela y sobrescribe los archivos en tu servidor. Mantén tus módulos personalizados, temas y archivos de configuración. Este enfoque es arriesgado porque la base de datos puede haber sido parcialmente migrada, creando una inconsistencia entre los archivos y el esquema de la base de datos.

Corrección hacia adelante: A veces el camino más rápido no es volver atrás sino corregir el error específico. Si el error es causado por un único módulo u override incompatible, corregir o eliminar ese único componente puede tomar minutos comparado con horas para un rollback completo. Este enfoque es mejor cuando has identificado claramente la causa desde el mensaje de error.

La Importancia de los Respaldos de la Base de Datos

Cada sección de esta guía menciona los respaldos, y por una buena razón. Una base de datos de PrestaShop contiene cada producto, cada pedido, cada cuenta de cliente, cada configuración y cada pieza de contenido de tu tienda. Perderla significa perder los datos de tu negocio.

Los respaldos diarios automatizados no son opcionales para una tienda PrestaShop en producción. Configura el sistema de respaldo de tu proveedor de hosting, usa un módulo de respaldo de base de datos o configura un cron job que ejecute mysqldump a intervalos regulares. Almacena los respaldos en múltiples ubicaciones. Prueba tu procedimiento de restauración periódicamente para asegurarte de que los respaldos sean realmente utilizables.

Antes de cualquier actualización, crea un respaldo manual además de tus respaldos automatizados. Nómbralo claramente con la fecha y la versión de PrestaShop, para que puedas identificarlo inmediatamente si necesitas restaurar.

Cuándo Buscar Ayuda Profesional

Si has seguido todos los pasos de esta guía y sigues enfrentando una página en blanco, o si los mensajes de error apuntan a problemas profundos del core que requieren correcciones a nivel de código, puede ser el momento de contratar a un desarrollador PrestaShop. Proporciónale los mensajes de error que recopilaste, las versiones de PrestaShop involucradas (antes y después de la actualización), tu versión de PHP y cualquier acción que ya hayas tomado. Esta información reducirá significativamente el tiempo necesario para diagnosticar y resolver el problema.

Intentar editar manualmente los archivos core de PrestaShop sin comprender la arquitectura del framework puede crear problemas adicionales. Si el mensaje de error hace referencia a contenedores Symfony, inyección de dependencias o configuración del kernel, estas son áreas donde los cambios incorrectos pueden propagarse en múltiples fallos.