Una pantalla blanca de la muerte PrestaShop es una página en blanco sin mensaje – front office, Back Office, o ambos. Normalmente significa que PHP se detuvo antes de que la tienda pudiera renderizar el HTML. Esta guía muestra cómo activar el modo debug (incluso cuando el panel de administración está caído), leer el error real y aplicar las soluciones que resuelven la mayoría de los casos de WSoD.
Desde PrestaShop 1.7 en adelante (incluyendo 8 y 9), las opciones de depuración se encuentran en Parámetros avanzados → Rendimiento cuando el Back Office todavía carga. Si la administración también está en blanco, debes cambiar _PS_MODE_DEV_ en config/defines.inc.php a través de SFTP o SSH. Las notas oficiales sobre esta pantalla están en la documentación de rendimiento de PrestaShop 9. Haz una copia de seguridad completa de PrestaShop antes de eliminar módulos o restaurar archivos.
Qué significa normalmente una pantalla blanca de la muerte PrestaShop
La página en blanco es un síntoma, no un único error. Una pantalla blanca de la muerte PrestaShop significa que PHP encontró un error fatal, se quedó sin memoria o falló antes de que Smarty pudiera imprimir algo. El modo de producción oculta ese detalle a propósito – para que los compradores nunca vean el rastro de la pila de errores. Tu trabajo es hacer visible el error y luego solucionar la causa.
Observa dónde falla:
- Solo en el front – a menudo un override del tema, un hook de módulo o un artefacto de caché en la tienda
- Solo en el Back Office – a menudo un módulo de administración, una pestaña o un override en
override/ - En ambos – credenciales de base de datos incorrectas,
defines.inc.phproto, caída de la versión de PHP o un error fatal que se ejecuta en cada petición
Paso 1: Activar el modo debug
El modo debug imprime la excepción (o te dirige al registro) en lugar de una página en blanco. Es preferible usar el Back Office cuando todavía se abre.
- Inicia sesión en el Back Office.
- Ve a Parámetros avanzados → Rendimiento.
- En el bloque Modo debug, establece Modo debug en Sí.
- Haz clic en Guardar.
- Recarga la URL en blanco en una ventana privada.
Si el Back Office también es una pantalla blanca de la muerte PrestaShop, edita el archivo en el disco. Descarga primero una copia de config/defines.inc.php (incluso si ya hiciste una copia de seguridad completa) para poder restaurar el original con un clic si la edición sale mal:
- Abre
config/defines.inc.phpa través de SFTP, SSH o el administrador de archivos del hosting y guarda una copia local. - Busca
define('_PS_MODE_DEV_', false);(la redacción puede variar ligeramente según la versión). - Cámbialo a
define('_PS_MODE_DEV_', true);y guarda. - Recarga la página que falla.
Vuelve a desactivar el modo debug cuando hayas terminado. Dejarlo activado en producción expone las rutas y los rastros de la pila a cualquiera que encuentre un error.
Paso 2: Identificar el error
Con el modo debug activado, la pantalla blanca de la muerte PrestaShop normalmente se convierte en una excepción legible. Toma nota del nombre de la clase, el nombre del módulo, la ruta del archivo en modules/, themes/ o override/, y el número de línea. Esa cadena suele ser suficiente para elegir la solución correcta a continuación.
Si la página sigue en blanco incluso con _PS_MODE_DEV_ en true, revisa el registro de errores PHP del hosting (cPanel, Plesk o var/logs/ en algunas configuraciones). Un error de análisis en un archivo de configuración puede detener la ejecución antes de que se inicie la capa de depuración de PrestaShop.
Fuentes comunes:
- Personalizaciones recientes – ediciones del tema, overrides o fragmentos de código copiados
- Módulos – especialmente un módulo instalado o actualizado justo antes de la caída
- Cambios en el hosting – actualización de la versión de PHP, extensión faltante, límite de memoria más bajo
- Credenciales de base de datos – valores incorrectos en
app/config/parameters.phptras una migración - Permisos de archivos – PHP no puede leer un archivo requerido o escribir en la caché
- Límite de memoria – errores fatales que mencionan memoria agotada
- Caché obsoleta – plantillas compiladas rotas después de una actualización
Paso 3: Solucionar el error
Relaciona la salida del modo debug con una de las rutas. Cambia una cosa a la vez y luego recarga.
Personalizaciones y overrides
Deshaz el último cambio en el tema o override si lo conoces. En Rendimiento, prueba Desactivar todos los overrides → Sí, guarda y vuelve a probar. Si la tienda vuelve a funcionar, el error está en override/ o en un override de módulo – corrige o elimina ese archivo en lugar de dejar los overrides desactivados para siempre.
Errores de módulos
En Rendimiento, establece Desactivar los módulos no desarrollados por PrestaShop → Sí y vuelve a probar. Si eso elimina la pantalla blanca de la muerte PrestaShop, renombra la carpeta del módulo sospechoso en modules/ (o desinstálalo desde el BO una vez que la administración funcione) uno por uno hasta encontrar al culpable. Es preferible renombrar a eliminar para poder restaurar los archivos después de identificarlo.
Hosting y PHP
Compara Parámetros avanzados → Información con lo que el hosting dice que están ejecutando. Después de una actualización de PHP, las extensiones faltantes o un manejo de errores más estricto a menudo se manifiestan como una página en blanco. Pregunta al hosting qué versión de PHP y memory_limit utiliza realmente el vhost.
Conexión a la base de datos
Si el modo debug menciona el acceso a la base de datos o la tienda se cayó justo después de un cambio de servidor, verifica el host, nombre, usuario y contraseña en app/config/parameters.php. Los pasos completos están en nuestra guía sobre cómo cambiar la configuración de conexión a la base de datos en PrestaShop.
Permisos y memoria
Cuando el error nombra un archivo que PHP no puede abrir, corrige la propiedad/permisos de esa ruta (propiedad típica del usuario web; evita 777 como solución permanente). Para errores de memoria agotada, aumenta el memory_limit en el php.ini del vhost o pregunta al hosting – luego borra la caché y vuelve a probar.
Caché
Desde Rendimiento, haz clic en Borrar la caché. Si el BO está caído, elimina el contenido de var/cache/prod/ (y var/cache/dev/ si está presente) a través del administrador de archivos o SSH, manteniendo las carpetas en sí. Los árboles de caché enormes suelen ser más fáciles de vaciar desde SSH que desde FTP.
Paso 4: Cuando todavía necesitas ayuda
Si el modo debug está activado, los módulos/overrides están aislados, las credenciales coinciden y todavía tienes una pantalla blanca de la muerte PrestaShop, recopila: el texto exacto del error, la versión de PrestaShop, la versión de PHP y qué cambió por última vez (módulo, despliegue, actualización del hosting). Publica eso en los foros de PrestaShop, o envíalo a tu hosting o a un desarrollador que pueda leer los registros del servidor que no puedes ver solo desde la tienda.
Paso 5: Restaurar desde una copia de seguridad
Restaurar archivos o un volcado de base de datos es el último recurso – pierdes los cambios realizados después de esa copia de seguridad. Úsalo cuando un mal despliegue no se puede revertir rápidamente y ya tienes una copia reciente. Cómo hacer y mantener esas copias se explica en la guía de copias de seguridad de PrestaShop.
Lista de verificación rápida
- Activa el modo debug (Rendimiento en el BO, o
_PS_MODE_DEV_endefines.inc.php). - Lee el error en pantalla o el registro de PHP.
- Aísla los overrides y los módulos no nativos desde Rendimiento.
- Corrige las credenciales de la base de datos, permisos, memoria o caché según indique el mensaje.
- Desactiva el modo debug; restaura desde una copia de seguridad solo si nada más recupera la tienda.
La mayoría de los casos de pantalla blanca de la muerte PrestaShop se resuelven una vez que el mensaje real de PHP es visible. Empieza con el modo debug, cambia una variable a la vez y mantén una copia de seguridad lista antes de eliminar cualquier cosa que no puedas recuperar.