Errores al instalar módulos PrestaShop: soluciones | FAQ

Introducción: ¿Por qué falla un módulo en PrestaShop?

Instalar un módulo en PrestaShop debería ser un proceso sencillo, pero a veces te encuentras con el temido error instalar módulo PrestaShop que te impide añadir nuevas funcionalidades a tu tienda. No te preocupes, es más común de lo que crees y, en la mayoría de los casos, tiene solución.

En esta guía extensa, vamos a desglosar los errores más frecuentes al trabajar con módulos PrestaShop fallo, explicando por qué ocurren y, lo más importante, cómo solucionar módulo PrestaShop paso a paso. Tanto si eres nuevo en el mundo del ecommerce como si ya tienes experiencia, este artículo te servirá como manual de referencia.

Error 1: El módulo no se sube o no aparece en la lista

Este es uno de los primeros tropiezos. Subes el archivo ZIP del módulo, pero no aparece en la lista de módulos instalados o directamente la subida falla.

Causas comunes

Tamaño del archivo excesivo: PrestaShop tiene un límite de subida por defecto (normalmente 2MB o 8MB). Si tu módulo pesa más, no se subirá.
Permisos de carpeta incorrectos: El servidor necesita permisos de escritura en la carpeta /modules para poder descomprimir el archivo.
Formato del ZIP incorrecto: El archivo ZIP debe contener una carpeta con el nombre del módulo y dentro los archivos. Si el ZIP contiene solo archivos sueltos, no funcionará.

Soluciones paso a paso

Verifica el límite de subida:
- Ve a Configuración avanzada > Información del servidor en tu backoffice de PrestaShop.
- Busca los valores upload_max_filesize y post_max_size. Si son menores a 20MB, pide a tu hosting que los aumente.
- Si usas Syspanel (antes HestiaCP), puedes ajustar estos valores desde el panel de administración (puerto 2106) en la sección de configuración PHP.
Corrige los permisos de la carpeta modules:
- Conéctate a tu servidor vía FTP o desde el administrador de archivos de Syspanel.
- Navega a la carpeta raíz de PrestaShop y localiza la carpeta /modules.
- Establece permisos 755 para la carpeta y 644 para los archivos dentro de ella.
Revisa la estructura del ZIP:
- Descomprime el ZIP en tu ordenador. Deberías ver una carpeta (ej: mimodulo). Vuelve a comprimir solo esa carpeta, no los archivos sueltos.
- Vuelve a intentar la subida desde el backoffice: Módulos > Administrador de módulos > Subir un módulo.

[TIP] Si el error persiste, usa un gestor FTP para subir la carpeta del módulo directamente a /modules y luego actívalo desde el backoffice.

Error 2: El módulo da error de compatibilidad o versión

Otro clásico: instalas el módulo y te aparece un mensaje como "Este módulo no es compatible con tu versión de PrestaShop" o directamente no funciona.

Causas comunes

Módulo desactualizado: El módulo fue diseñado para una versión anterior de PrestaShop (1.6, 1.7) y no se actualizó para la 8.x.
Dependencias faltantes: Algunos módulos requieren librerías PHP específicas (como cURL, JSON, etc.) que no están habilitadas en tu servidor.
Conflictos con otros módulos: Dos módulos intentan modificar el mismo hook o función.

Soluciones paso a paso

Verifica la compatibilidad:
- Antes de comprar o descargar un módulo, revisa la ficha del producto: debe indicar claramente las versiones de PrestaShop soportadas.
- Si ya lo tienes instalado, ve a Módulos > Administrador de módulos y busca el módulo. Haz clic en "Configurar" para ver si hay una actualización disponible.
Actualiza PHP y extensiones:
- Desde Syspanel (puerto 2106), ve a la sección de configuración PHP y asegúrate de tener habilitadas las extensiones: curl, json, mbstring, openssl, pdo_mysql.
- Cambia la versión de PHP a 7.4 o 8.0 (según lo que soporte el módulo). PrestaShop 8.x funciona mejor con PHP 8.0 o 8.1.
Desactiva módulos conflictivos:
- Ve a Módulos > Administrador de módulos y desactiva temporalmente otros módulos que puedan interferir (especialmente los que modifican el catálogo o el carrito).
- Prueba a activar el módulo problemático. Si funciona, ve activando uno por uno los demás hasta detectar el conflicto.

[WARNING] No actualices PrestaShop a una versión superior si no estás seguro de que todos tus módulos críticos sean compatibles. Haz siempre una copia de seguridad antes.

Error 3: El módulo se instala pero da error 500 o página en blanco

Este es uno de los errores más frustrantes. El módulo aparece como instalado, pero al intentar acceder a su configuración o a alguna página de la tienda, obtienes un error 500 o una pantalla en blanco.

Causas comunes

Error de sintaxis en el código del módulo: Puede ocurrir si el módulo tiene un bug o si hubo un error al descargarlo.
Memoria insuficiente: El módulo requiere más memoria de la que tiene asignada PHP.
Hook mal implementado: El módulo intenta ejecutar una función en un hook que no existe o está mal definido.

Soluciones paso a paso

Activa el modo debug de PrestaShop:
- Edita el archivo /config/defines.inc.php (conéctate vía FTP).
- Busca la línea define('_PS_MODE_DEV_', false); y cámbiala a define('_PS_MODE_DEV_', true);.
- Guarda el archivo y recarga la página. Ahora verás el error real (por ejemplo, "Fatal error: Class not found").
- Una vez resuelto, vuelve a poner false para no mostrar errores a los clientes.
Aumenta la memoria de PHP:
- En Syspanel (puerto 2106), ve a Configuración PHP y busca memory_limit. Súbelo a 256M o 512M.
- También puedes editarlo desde el archivo php.ini (normalmente en /etc/php/8.0/apache2/php.ini o similar).
Desactiva el módulo desde la base de datos (si no puedes acceder al backoffice):
- Conéctate a la base de datos de PrestaShop usando phpMyAdmin (desde Syspanel).
- Busca la tabla ps_module (el prefijo puede variar). Localiza el módulo problemático y cambia active de 1 a 0.
- Luego desinstálalo desde el backoffice (si puedes acceder) o elimina su carpeta en /modules.

[INFO] Si el error 500 aparece en toda la tienda, no solo en el módulo, el problema puede ser más grave (ej: error en el tema). Sigue los pasos de debug para identificarlo.

Error 4: El módulo no se actualiza correctamente

A veces, al intentar actualizar un módulo desde el backoffice, el proceso se queda colgado o da un error.

Causas comunes

Fallo en la descarga del ZIP: El servidor de PrestaShop o del desarrollador puede estar temporalmente caído.
Permisos insuficientes: La carpeta del módulo no tiene permisos de escritura para sobrescribir archivos.
Versión del módulo incompatible con la nueva actualización.

Soluciones paso a paso

Actualiza manualmente:
- Descarga la última versión del módulo desde la web del desarrollador.
- Conéctate vía FTP y elimina la carpeta completa del módulo en /modules (haz una copia de seguridad primero).
- Sube la nueva carpeta del módulo y actívalo desde el backoffice.
Limpia la caché:
- Ve a Configuración avanzada > Rendimiento > Forzar compilación y limpia la caché.
- También puedes borrar manualmente la carpeta /var/cache (en PrestaShop 1.7+) o /cache (en versiones antiguas).
Verifica los requisitos del módulo:
- Revisa si la nueva versión requiere una versión específica de PHP o de PrestaShop. Si no cumples, no podrás actualizar.

[TIP] Siempre que actualices un módulo, hazlo primero en un entorno de pruebas (staging) para evitar sorpresas en tu tienda en producción.

Error 5: El módulo no se desinstala o deja rastros

Otro problema común: desinstalas un módulo, pero sigue apareciendo en la lista o deja tablas en la base de datos.

Causas comunes

El módulo no tiene un método de desinstalación correcto: Algunos módulos dejan datos huérfanos.
Fallo en la base de datos: La tabla ps_module o ps_hook_module puede estar corrupta.

Soluciones paso a paso

Desinstala desde el backoffice:
- Ve a Módulos > Administrador de módulos, busca el módulo y haz clic en "Desinstalar".
- Si aparece un error, intenta desactivarlo primero y luego desinstalarlo.
Elimina manualmente:
- Conéctate vía FTP y elimina la carpeta del módulo en /modules.
- Conéctate a la base de datos (phpMyAdmin) y busca tablas con el nombre del módulo (ej: ps_mimodulo). Bórralas con cuidado.
- También revisa la tabla ps_configuration y elimina las filas que tengan el nombre del módulo en la columna name.
Usa un módulo de limpieza (si puedes instalar uno):
- Módulos como "Cleaner" o "Advanced Cleaner" pueden ayudarte a eliminar rastros de módulos desinstalados.

[WARNING] Si no estás seguro de qué tablas borrar, consulta con un desarrollador. Eliminar datos incorrectos puede romper tu tienda.

Preguntas frecuentes (FAQ)

¿Por qué aparece "error instalar módulo PrestaShop" al subir un ZIP?

Puede deberse al tamaño del archivo (límite de subida), permisos de la carpeta /modules o un ZIP mal formado. Revisa los pasos del Error 1.

¿Qué hago si un módulo da "módulos PrestaShop fallo" después de una actualización de PrestaShop?

Primero, verifica la compatibilidad del módulo con la nueva versión. Si no es compatible, busca una actualización del módulo o contacta al desarrollador. Temporalmente, puedes desactivarlo.

¿Cómo puedo solucionar módulo PrestaShop que da error 500?

Activa el modo debug (cambiando _PS_MODE_DEV_ a true en /config/defines.inc.php) para ver el error exacto. Luego, sigue los pasos del Error 3.

¿Es seguro eliminar manualmente un módulo desde FTP?

Sí, pero antes desinstálalo desde el backoffice si es posible. Si no, elimina la carpeta y luego limpia las tablas de la base de datos relacionadas. Siempre haz una copia de seguridad.

¿Cada cuánto debo actualizar los módulos de PrestaShop?

Revisa las actualizaciones al menos una vez al mes. Las actualizaciones suelen corregir bugs de seguridad y compatibilidad.

Conclusión: La paciencia y el método son clave

Enfrentarse a un error instalar módulo PrestaShop puede ser desesperante, pero como has visto, la mayoría de los problemas tienen una solución lógica y sencilla. La clave está en:

Identificar la causa: Lee el mensaje de error, activa el modo debug si es necesario.
Aplicar la solución adecuada: Desde ajustar permisos hasta actualizar PHP.
Prevenir futuros errores: Mantén todo actualizado (PrestaShop, módulos, PHP) y usa siempre módulos de fuentes confiables.

Recuerda que tu hosting juega un papel fundamental. Si usas Syspanel (accesible en el puerto 2106), tienes herramientas potentes para gestionar PHP, bases de datos y archivos. Aprovéchalas.

Si después de seguir todos estos pasos el problema persiste, no dudes en contactar al soporte técnico de tu hosting o al desarrollador del módulo. Con un poco de paciencia, tu tienda volverá a funcionar a la perfección.

¡Buena suerte con tus módulos!