Errores comunes en PrestaShop al instalar módulos: Soluciones

¡Hola! Soy tu técnico de soporte amigable. Si estás aquí es porque PrestaShop te está dando algún dolor de cabeza al intentar instalar un módulo nuevo. No te preocupes, es una de las consultas más habituales que recibimos. Instalar módulos es la forma más rápida de añadir funcionalidades a tu tienda, pero a veces el proceso se complica con errores que parecen chinos.

En esta guía vamos a desglosar los errores más comunes al instalar módulos en PrestaShop, entender por qué ocurren y, lo más importante, darte una solución paso a paso. Todo explicado de forma sencilla, sin tecnicismos raros. Al final de este artículo, podrás resolver el 90% de los problemas tú mismo. ¡Vamos allá!

Entendiendo el proceso de instalación de módulos en PrestaShop

Antes de meternos en harina, es bueno que sepas cómo funciona esto por dentro. Cuando instalas un módulo en PrestaShop, el sistema tiene que hacer varias cosas: descomprimir el archivo ZIP que subes, copiar los archivos a la carpeta correcta de tu servidor, registrar el módulo en la base de datos y, por último, activarlo. Cualquier fallo en uno de estos pasos genera el error.

¿Dónde se instalan los módulos? Normalmente lo haces desde el panel de administración de tu tienda (Back Office) en la sección "Módulos" -> "Gestor de Módulos". También puedes subir archivos manualmente por FTP, pero es más técnico.

¿Qué necesitas para instalarlos? Un módulo válido (normalmente un archivo .zip), permisos de escritura en las carpetas de PrestaShop y, a veces, requisitos específicos del módulo (como una versión concreta de PHP).

Error 1: "El archivo no se puede descomprimir" o "Error al subir el archivo"

Este es el error más frustrante porque parece que el sistema no reconoce el archivo. Las causas suelen ser dos: el archivo ZIP está corrupto o no es un módulo válido de PrestaShop.

¿Por qué pasa?

El archivo se descargó incompleto (por ejemplo, por un corte de internet).
El desarrollador del módulo empaquetó mal el ZIP (a veces incluye subcarpetas incorrectas).
El tamaño del archivo supera el límite permitido por tu servidor (límite de subida de PHP).

Solución paso a paso

Verifica el archivo ZIP: Descárgalo de nuevo desde la fuente oficial. Asegúrate de que el peso del archivo coincide con el que indica el vendedor o la documentación.
Comprueba la estructura interna: Descomprime el ZIP en tu ordenador. Dentro deberías ver una carpeta con el nombre del módulo (ej: micodigo) y dentro archivos como micodigo.php, index.php, etc. Si ves otra carpeta dentro, el empaquetado es incorrecto.
Aumenta el límite de subida: Si el módulo pesa más de 20 MB, probablemente tu servidor lo rechace. Puedes aumentar este límite editando el archivo php.ini. Si usas Syspanel (panel de control, accesible por puerto 2106), busca la sección "PHP Settings" y ajusta upload_max_filesize y post_max_size a 64M o más.
Usa FTP como alternativa: Si todo falla, sube el módulo manualmente. Descomprime el ZIP, conecta por FTP a tu hosting, navega hasta la carpeta /modules de tu PrestaShop y sube allí la carpeta del módulo. Luego ve al Back Office y actívalo desde el Gestor de Módulos.

[TIP] Si usas Syspanel, puedes gestionar los límites de PHP desde el panel con un solo clic. Es mucho más fácil que editar archivos manualmente.

Error 2: "El módulo no es compatible con tu versión de PrestaShop"

Este error aparece cuando intentas instalar un módulo diseñado para una versión más reciente o más antigua de PrestaShop. Es muy común si tienes una tienda antigua y el módulo es moderno, o viceversa.

¿Por qué pasa?

El módulo usa funciones que no existen en tu versión de PrestaShop.
El desarrollador no actualizó el módulo para tu versión.
Tu PrestaShop está muy desactualizado.

Solución paso a paso

Comprueba tu versión de PrestaShop: En el Back Office, ve a "Parámetros de la tienda" -> "Información" y anota el número de versión (ej: 1.7.8.10).
Consulta la ficha del módulo: En la página de descarga o en el marketplace, busca "Compatibilidad" o "Versiones soportadas". Si no coincide con la tuya, no lo instales a la fuerza.
Actualiza PrestaShop (si es posible): Si tu versión es muy antigua (por ejemplo, 1.6), considera migrar a 1.7 o 8.x. Muchos módulos modernos solo funcionan en versiones recientes. Esto es un proceso delicado, así que haz una copia de seguridad antes.
Busca una versión anterior del módulo: Algunos desarrolladores ofrecen versiones para PrestaShop 1.6 o 1.7. Contacta con el soporte del módulo.
Modificación manual (solo para expertos): Si sabes de programación, puedes editar el archivo config.xml dentro del ZIP del módulo y cambiar la versión mínima requerida. Pero esto puede romper tu tienda, así que no lo recomiendo si no tienes experiencia.

[WARNING] Forzar la instalación de un módulo incompatible puede desestabilizar tu tienda, causar errores en el front-end o incluso perder datos. Siempre prueba en un entorno de desarrollo primero.

Error 3: "Error al instalar el módulo: no se puede escribir en la carpeta"

Este error es típico de problemas de permisos en el servidor. PrestaShop necesita poder escribir en ciertas carpetas para instalar módulos, y si no tiene permiso, se bloquea.

¿Por qué pasa?

La carpeta /modules o sus subcarpetas tienen permisos incorrectos (por ejemplo, 755 en lugar de 775).
El propietario de los archivos no es el usuario del servidor web (www-data, nobody, etc.).
Hay un plugin de seguridad (como un firewall) que bloquea la escritura.

Solución paso a paso

Verifica los permisos actuales: Conéctate por FTP a tu hosting. Ve a la carpeta raíz de PrestaShop (donde están las carpetas admin, modules, img, etc.). Haz clic derecho en la carpeta modules y selecciona "Permisos" o "CHMOD". Debería ser 755 o 775. Si ves 644 o 444, hay que cambiarlo.
Cambia los permisos: En tu cliente FTP, selecciona la carpeta modules y todas las subcarpetas, y establece los permisos a 755 (lectura y ejecución para todos, escritura para el propietario). Si usas Syspanel, puedes hacerlo desde el gestor de archivos: selecciona la carpeta, haz clic en "Permisos" y pon 0755.
Ajusta el propietario: Si tu hosting usa Syspanel, ve a "Archivos" -> "Gestor de Archivos", selecciona la carpeta modules, y en "Propietario" asegúrate de que sea el mismo usuario que ejecuta PHP (normalmente admin o www-data). Si no sabes cuál es, contacta con soporte.
Desactiva temporalmente el firewall: Si tienes un plugin de seguridad como "Security" o "Firewall", desactívalo momentáneamente, instala el módulo y luego actívalo de nuevo.

[INFO] Los permisos 755 significan: el propietario puede leer, escribir y ejecutar; el grupo y otros solo pueden leer y ejecutar. Es el estándar seguro para la mayoría de los servidores.

Error 4: "Error de base de datos: tabla no encontrada" o "Error SQL"

Este error ocurre cuando el módulo intenta crear o modificar tablas en la base de datos y algo sale mal. Puede deberse a que la base de datos está llena, a un prefijo incorrecto o a un fallo en el código SQL del módulo.

¿Por qué pasa?

El módulo intenta crear una tabla que ya existe (conflicto con otro módulo).
El prefijo de las tablas de PrestaShop no coincide con el que espera el módulo.
La base de datos tiene un límite de tamaño o de conexiones.
El módulo tiene un error de programación en sus consultas SQL.

Solución paso a paso

Revisa el prefijo de las tablas: En tu Back Office, ve a "Parámetros avanzados" -> "Base de datos". Anota el prefijo (normalmente ps_). Si el módulo usa otro prefijo, no funcionará. Puedes editar el archivo del módulo (en /modules/tumodulo/tumodulo.php) y buscar DB_PREFIX para cambiarlo manualmente.
Limpia la caché de PrestaShop: A veces una caché corrupta causa errores de base de datos. Ve a "Parámetros avanzados" -> "Rendimiento" y haz clic en "Limpiar caché". También puedes borrar la carpeta /var/cache por FTP.
Aumenta los límites de la base de datos: Si tu hosting usa Syspanel, ve a "Base de datos" -> "phpMyAdmin". Selecciona tu base de datos y revisa el tamaño. Si está cerca del límite, necesitas más espacio. Contacta con tu proveedor.
Desinstala módulos conflictivos: Si el error dice "tabla ya existe", busca qué otro módulo usa esa tabla y desinstálalo temporalmente.
Ejecuta la consulta manualmente: Si eres avanzado, abre phpMyAdmin, selecciona tu base de datos, y pega el SQL que viene en el archivo install.sql del módulo. A veces el instalador automático falla pero la consulta manual funciona.

[WARNING] No modifiques la base de datos directamente si no estás seguro. Un error puede borrar datos de tu tienda. Siempre haz una copia de seguridad antes.

Error 5: "El módulo no se muestra en el listado" o "Error 500 después de instalar"

Este es un error genérico que suele deberse a un conflicto con otros módulos, un error de PHP o una mala configuración del servidor.

¿Por qué pasa?

El módulo tiene un error de sintaxis en su código PHP.
Hay un conflicto con otro módulo activo.
La memoria PHP asignada es insuficiente.
El servidor tiene una versión de PHP incompatible (por ejemplo, el módulo requiere PHP 8.0 pero tu servidor tiene PHP 7.4).

Solución paso a paso

Activa el modo debug de PrestaShop: Edita el archivo /config/defines.inc.php y cambia _PS_MODE_DEV_ a true. Esto mostrará el error exacto en pantalla. Anota el mensaje (por ejemplo, "Fatal error: Uncaught Error: Call to undefined function").
Verifica la versión de PHP: En tu Back Office, ve a "Parámetros avanzados" -> "Información". Busca "Versión de PHP". Si es menor a la que requiere el módulo, debes actualizarla. En Syspanel, ve a "PHP Settings" y selecciona una versión más reciente (como 8.0 o 8.1).
Aumenta la memoria PHP: En el mismo Syspanel, busca "memory_limit" y súbelo a 256M o 512M. También puedes hacerlo editando php.ini.
Desactiva módulos uno por uno: Ve a "Módulos" -> "Gestor de Módulos", desactiva todos los módulos excepto el nuevo, y ve activándolos de uno en uno hasta encontrar el conflicto.
Reinstala el módulo: A veces una instalación fallida deja residuos. Desinstala el módulo desde el Back Office (si aparece), borra su carpeta en /modules por FTP, y vuelve a instalarlo desde cero.

[TIP] Si usas Syspanel, puedes cambiar la versión de PHP y los límites de memoria desde el panel en menos de un minuto. Es mucho más rápido que buscar archivos de configuración.

Error 6: "Error de conexión FTP" o "No se puede conectar al servidor FTP"

Este error es menos común hoy en día, pero aún aparece cuando el módulo intenta descargar actualizaciones o instalar dependencias desde un servidor externo y la conexión falla.

¿Por qué pasa?

Tu servidor bloquea las conexiones salientes (por seguridad).
El firewall del hosting impide la conexión a ciertos puertos (por ejemplo, puerto 21 para FTP).
El módulo necesita autenticación FTP y no la tiene configurada.

Solución paso a paso

Verifica la conectividad de tu servidor: Prueba a hacer un ping a google.com desde la terminal de tu hosting (si tienes acceso SSH). Si no hay respuesta, contacta con soporte.
Configura un proxy o cambia a HTTPS: Algunos módulos permiten usar HTTP en lugar de FTP. Busca en la configuración del módulo una opción como "Usar conexión segura" o "Proxy".
Desactiva el firewall temporalmente: Si tu hosting tiene un firewall como CSF o iptables, pide a soporte que permita las conexiones salientes al puerto 21 o 443.
Instala manualmente las dependencias: Si el módulo necesita descargar librerías externas, descárgalas tú mismo desde la web del desarrollador y súbelas por FTP a la carpeta del módulo.

[INFO] La mayoría de los módulos modernos ya no usan FTP para instalarse, sino que descargan archivos por HTTP/HTTPS. Si ves este error, es posible que el módulo sea muy antiguo.

Preguntas Frecuentes (FAQ)

¿Por qué algunos módulos no se instalan aunque sigan todos los pasos?

A veces el problema es del propio módulo: puede tener un error de programación o estar mal empaquetado. Prueba a descargarlo de nuevo o contacta al desarrollador. También revisa que no haya conflictos con otros módulos.

¿Es seguro instalar módulos de terceros?

Depende de la fuente. Siempre compra en marketplaces oficiales (PrestaShop Addons) o de desarrolladores reputados. Los módulos gratuitos de sitios desconocidos pueden contener malware.

¿Cómo puedo saber qué versión de PHP necesita mi módulo?

Revisa la documentación del módulo o el archivo config.xml dentro del ZIP. Busca la etiqueta <php> que indica la versión mínima.

¿Qué hago si después de instalar un módulo mi tienda deja de cargar?

Accede al Back Office por URL directa (ej: tutienda.com/admin). Si no puedes, desactiva el módulo por FTP: renombra la carpeta del módulo en /modules (por ejemplo, de micodigo a micodigo_old). Luego limpia la caché.

¿Syspanel ayuda a solucionar estos errores?

Sí, mucho. En Syspanel (accesible por puerto 2106) puedes cambiar la versión de PHP, ajustar límites de memoria y subida, gestionar permisos de archivos y ver logs de errores. Todo desde una interfaz gráfica, sin necesidad de editar archivos de configuración.

Conclusión

Instalar módulos en PrestaShop no tiene por qué ser un dolor de cabeza. La mayoría de los errores se deben a problemas de permisos, compatibilidad de versiones o límites del servidor. Con esta guía, ya tienes las herramientas para diagnosticar y solucionar los problemas más comunes.

Recuerda siempre hacer una copia de seguridad de tu tienda antes de instalar cualquier módulo nuevo, y si el error persiste, no dudes en contactar con tu proveedor de hosting o con el soporte del módulo. ¡Tu tienda online merece funcionar sin problemas!

Si usas Syspanel, aprovecha sus herramientas para gestionar PHP y archivos: te ahorrará tiempo y disgustos. Y si tienes alguna duda más, aquí estoy para ayudarte. ¡Buena suerte con tu instalación!