Error 500 o pantalla en blanco tras instalar un módulo
Si acabas de instalar un módulo y la tienda se ha quedado en blanco o muestra un error 500, aquí tienes los pasos para recuperarla de inmediato.
Jose Rosado · 5 de octubre de 2026 · 7 min de lectura
Subes el archivo ZIP del módulo, pulsas en instalar y, al recargar la página, la tienda desaparece. En su lugar aparece un error 500 o una pantalla completamente vacía, y en muchos casos tampoco puedes entrar al panel de administración.
Es uno de los momentos más estresantes cuando gestionas una tienda online. En Joyería HAGO, con nuestra tienda en PrestaShop 8 y dos tiendas físicas en Málaga, nos hemos encontrado con esta situación varias veces a lo largo de los años. La buena noticia es que la tienda no se ha roto para siempre: los datos de tus clientes, tus pedidos y tu catálogo siguen ahí. Solo necesitas desactivar lo que está interrumpiendo la carga de PHP y diagnosticar la causa.
El primer paso: recuperar la tienda desactivando el módulo por FTP
Si la tienda no responde y ni siquiera te deja entrar al panel de gestión, no intentes reinstalar nada a ciegas. Lo primero es hacer que la web vuelva a ser visible para tus clientes.
Cuando PrestaShop intenta cargar la página, recorre los módulos activos y ejecuta su código. Si el módulo nuevo tiene un error fatal, interrumpe la carga de todo el sistema. Para detenerlo de inmediato, el método más rápido es acceder a los archivos de tu servidor mediante un cliente de FTP o el administrador de archivos del panel de tu alojamiento web:
- Accede a la raíz de tu instalación de PrestaShop y entra en la carpeta
/modules/. - Busca la carpeta que corresponde al módulo que acabas de subir. Tendrá el nombre técnico del módulo (por ejemplo, el nombre interno con el que venía el archivo comprimido).
- Cambia el nombre de esa carpeta. Basta con añadirle algo al final, por ejemplo cambiando el nombre a
modulo_desactivado.
Al cambiar el nombre de la carpeta, PrestaShop ya no encuentra el archivo principal del módulo cuando intenta cargarlo. En ese instante ignora el módulo y la tienda vuelve a cargar con normalidad. No has borrado ningún dato ni has desinstalado nada: simplemente has evitado que su código se ejecute.
Cómo ver el fallo real activando el modo depuración
Un error 500 o una pantalla en blanco en PrestaShop son simplemente formas genéricas que tiene el servidor de avisar de que ha ocurrido un error grave de PHP, ocultando los detalles técnicos para proteger la seguridad de la web. Sin embargo, para solucionar el problema necesitas saber exactamente qué archivo y qué línea están fallando.
Para ver el mensaje de error completo, necesitas activar el modo depuración en PrestaShop. Si todavía puedes entrar al panel de administración, la ruta es muy directa:
- En el menú lateral, dirígete a Parámetros avanzados > Rendimiento.
- Busca la opción de modo depuración y márcala como activada.
- Guarda los cambios.
Al recargar la página que antes fallaba, ya no verás una pantalla vacía. PrestaShop mostrará una pantalla con el mensaje exacto de PHP, indicando qué archivo ha provocado la parada. Si el panel de administración también está caído por el error, puedes consultar los registros de fallos directamente en el servidor, dentro del directorio /var/logs de tu tienda.
Las causas más habituales ordenadas de más a menos probable
Una vez que puedes identificar qué está ocurriendo o qué archivo interviene, estas son las causas más frecuentes por las que falla un módulo recién instalado, ordenadas de las que más solemos ver a las más aisladas.
1. Incompatibilidad de versión entre PrestaShop y PHP
Es la causa más común de una pantalla en blanco en PrestaShop tras una instalación. Cada versión de la plataforma está preparada para funcionar sobre unas versiones concretas de PHP. Por ejemplo, PrestaShop 8.0 y 8.1 funcionan con versiones de PHP que van desde la 7.2 hasta la 8.1. Por su parte, PrestaShop 9 ya pide versiones de PHP más modernas.
Si instalas un módulo diseñado para PrestaShop 1.7 en una tienda con PrestaShop 8, es muy habitual que utilice funciones antiguas de PHP o llamadas internas del núcleo que han desaparecido. Al ejecutarse en un entorno más moderno, PHP se detiene con un error fatal y bloquea la tienda. Antes de instalar un módulo, comprueba siempre en la información del desarrollador las versiones exactas de PrestaShop y de PHP con las que ha sido probado.
2. Choque entre overrides
Un override es un mecanismo que permite a un módulo modificar el comportamiento de una clase o de un controlador del núcleo de PrestaShop sin alterar los archivos originales. Al instalarse, el módulo copia sus modificaciones dentro del directorio /override/ de tu tienda.
El problema surge cuando dos módulos intentan modificar la misma función de la misma clase. En nuestra tienda nos ha ocurrido en varias ocasiones, especialmente con clases muy concurridas como las que controlan el carrito o el despachador de direcciones URL. Si el nuevo módulo intenta sobreescribir un método que ya estaba modificado por otro módulo anterior, la instalación falla o se genera un choque que deriva en un error 500 en PrestaShop.
Siempre que sea posible, es preferible utilizar módulos que funcionen mediante hooks en lugar de módulos que dependan de overrides, ya que los hooks son mucho más limpios a la hora de instalar, desactivar y convivir con otras herramientas.
3. Errores dentro de la ejecución de los hooks
Los hooks son los puntos de anclaje donde los módulos se enganchan para mostrar contenido o ejecutar tareas en momentos clave: en la cabecera (displayTop), en la portada (displayHome), en la ficha junto al botón de compra (displayProductAdditionalInfo) o al guardar un carrito (actionCartSave).
Algo que aprendimos con la tienda de pruebas de PluginPilot es que PrestaShop 8, cuando está en modo de producción, oculta los errores que ocurren dentro de ciertos hooks. El módulo simplemente no se ve y parece que no hace nada, o bien provoca un bloqueo silencioso en la carga de esa parte de la plantilla. Solo cuando activas el modo depuración se hace visible el fallo que estaba interrumpiendo el hook.
4. Caché corrupta o índice de clases desactualizado
PrestaShop almacena en caché las plantillas compiladas, la configuración general y un índice con todas las clases y overrides del sistema. A veces, tras subir un módulo o mover archivos, el sistema intenta cargar una versión previa que ya no coincide con lo que hay en el servidor.
Borrar la caché no corrige un fallo de programación, pero si el código es correcto y el error se debe a una referencia antigua a un archivo que ha cambiado de sitio, limpiar la caché suele bastar para restablecer la carga normal.
Resumen de síntomas y soluciones rápidas
Esta tabla resume los escenarios más habituales cuando una instalación interrumpe la tienda y la forma recomendada de actuar en cada uno:
| Síntoma en la tienda | Causa más probable | Acción inmediata |
|---|---|---|
| Pantalla totalmente en blanco en la tienda y en el panel | Error fatal de PHP (incompatibilidad de versión) | Renombrar la carpeta del módulo en /modules/ por FTP |
| Error 500 solo en páginas concretas (como el carrito) | Conflicto de override en esa clase o controlador | Revisar el contenido de la carpeta /override/ |
| El módulo se instala pero no muestra nada en la web | Fallo silencioso en un hook en modo producción | Activar el modo depuración para ver el error real |
| Error persistente tras corregir o desactivar el módulo | Caché de clases o plantillas desactualizada | Borrar la caché desde el panel o vaciarla en el servidor |
Qué orden de pasos seguir en la práctica
Si te encuentras ahora mismo con la tienda caída por este motivo, te recomendamos seguir exactamente este orden de actuación para resolverlo sin añadir problemas:
- Primero, recupera la tienda visible: entra por FTP a
/modules/y renombra la carpeta del módulo recién subido. Comprueba que el catálogo y el panel vuelven a cargar. - Segundo, limpia la memoria temporal: entra en Parámetros avanzados > Rendimiento y haz clic en el botón de borrar caché.
- Tercero, averigua el origen del fallo: si dispones de una tienda de pruebas (una réplica exacta de tu tienda en local o en un subdominio que no esté indexado por Google), instala allí el módulo y activa el modo depuración para leer el informe de error sin afectar a tus clientes.
- Cuarto, revisa los requisitos técnicos: comprueba que la versión del módulo se corresponde con tu versión exacta de PrestaShop y que tu versión de PHP está dentro del rango admitido por ambos.
En el comercio electrónico, los imprevistos ocurren cuando se hacen cambios directamente sobre la tienda que está vendiendo. Para evitar paradas innecesarias en futuras ocasiones, conviene revisar con calma cómo instalar un módulo en PrestaShop 8 sin romper la tienda, asegurando siempre una copia de seguridad reciente antes de subir cualquier archivo nuevo.