Errores al instalar módulos PrestaShop: Soluciones rápidas

Instalar módulos en PrestaShop puede parecer sencillo, pero a menudo surgen problemas que dejan a los comerciantes con la tienda en blanco, errores extraños o funcionalidades que no se activan. Como técnico de soporte, he visto miles de casos similares. Por eso, he preparado esta guía completa sobre los errores módulos PrestaShop más habituales y cómo solucionar problemas PrestaShop de forma rápida y sin pánico.

Vamos a desglosar cada error, desde el más común hasta el más técnico, con pasos claros que puedes seguir aunque no seas un experto en programación. Recuerda que la paciencia y el orden son tus mejores aliados.

Error 1: El módulo no se sube o no aparece en el listado

Este es el primer tropiezo. Subes el archivo ZIP, ves la barra de carga, pero luego el módulo no aparece en la lista de módulos instalados. O peor: te sale un mensaje de error genérico.

Causas principales

Archivo ZIP corrupto o incompleto: A veces la descarga desde el proveedor falla. El archivo puede estar dañado.
Extensión incorrecta: PrestaShop solo acepta archivos .zip. Si el archivo es .rar, .tar.gz o .7z, no funcionará.
Permisos de carpeta insuficientes: El servidor no tiene permisos para escribir en la carpeta de módulos (/modules).
Límite de tamaño de subida: El archivo ZIP supera el límite permitido por tu hosting (normalmente 2MB, 8MB o 20MB).

Soluciones paso a paso

Verifica el archivo ZIP: Descarga el módulo de nuevo desde la fuente oficial. Asegúrate de que no esté dañado. Puedes probar a abrirlo en tu ordenador con un programa como WinRAR o 7-Zip.
Comprueba la extensión: Renombra el archivo si es necesario. Solo debe terminar en .zip.
Aumenta los límites de subida: Accede al panel de control de tu hosting. Si usas Syspanel, recuerda que el puerto de acceso es el 2106. Busca la sección de "PHP" o "Configuración avanzada" y aumenta los valores de upload_max_filesize y post_max_size a 64M o 128M.
Revisa los permisos de la carpeta modules: Conéctate por FTP (FileZilla, por ejemplo) y asegúrate de que la carpeta /modules tenga permisos 755 o 775. Si no sabes cómo hacerlo, contacta con tu soporte técnico.

[WARNING] Nunca subas módulos desde fuentes no oficiales (foros, torrents, etc.). Suelen contener código malicioso o estar desactualizados, lo que provoca errores graves de seguridad.

Error 2: Pantalla blanca o error 500 al activar el módulo

Activas el módulo y ¡puf! Todo se vuelve blanco. Este es uno de los errores módulos PrestaShop más temidos, pero tiene solución.

Causas principales

Conflicto con otro módulo o tema: El nuevo módulo no es compatible con algo que ya tienes instalado.
Versión de PHP incorrecta: El módulo requiere una versión de PHP más moderna (o más antigua) que la que tiene tu tienda.
Error de sintaxis en el código: El módulo tiene un bug o está mal programado.
Memoria PHP insuficiente: El servidor no tiene suficiente memoria para ejecutar el módulo.

Soluciones paso a paso

Activa el modo debug de PrestaShop: Edita el archivo /config/defines.inc.php y cambia _PS_MODE_DEV_ de false a true. Esto mostrará el error real en lugar de la pantalla blanca. Anota el mensaje de error.
Desactiva el módulo desde la base de datos: Si no puedes acceder al panel de administración, usa phpMyAdmin (o la herramienta de bases de datos de tu hosting). Busca la tabla ps_module (el prefijo puede variar) y localiza el módulo conflictivo. Cambia su estado active de 1 a 0.
Aumenta la memoria PHP: En el archivo php.ini o desde Syspanel (puerto 2106), busca memory_limit y cámbialo a 256M o 512M.
Verifica la compatibilidad de versiones: Revisa la ficha del módulo. Debe indicar las versiones de PrestaShop y PHP compatibles. Si tu tienda usa PHP 7.4 y el módulo pide PHP 8.0, tendrás que actualizar PHP (con cuidado) o buscar un módulo alternativo.

[TIP] Si no sabes qué versión de PHP usas, ve a "Parámetros avanzados > Información" en tu back office de PrestaShop. Allí lo verás claramente.

Error 3: El módulo se instala pero no funciona correctamente

A veces el módulo aparece como instalado y activado, pero no hace lo que debería: no muestra el bloque, no envía emails, no se conecta a la pasarela de pago, etc.

Causas principales

Falta de configuración: Muchos módulos requieren pasos adicionales después de la instalación (API keys, URLs, etc.).
Caché obsoleta: PrestaShop guarda en caché archivos CSS, JS y plantillas. El módulo nuevo no se muestra porque la caché sigue siendo la antigua.
Problemas con las sobreescrituras (overrides): El módulo intenta modificar un archivo core que ya fue modificado por otro módulo.
Errores de JavaScript (JS): El módulo carga scripts que chocan con otros.

Soluciones paso a paso

Revisa la configuración del módulo: Ve a "Módulos > Gestor de módulos", busca el módulo y haz clic en "Configurar". Lee atentamente cada campo. Muchas veces solo falta pegar una clave o seleccionar una opción.
Limpia la caché de PrestaShop: En el back office, ve a "Parámetros avanzados > Rendimiento". Activa todas las opciones de "Forzar compilación" y "Limpiar caché". Luego desactívalas de nuevo. También puedes borrar manualmente la carpeta /var/cache (excepto el archivo index.php).
Limpia la caché del navegador y del servidor: A veces el problema es que tu navegador guarda una versión antigua. Prueba en modo incógnito. También puedes limpiar la caché de tu hosting desde Syspanel (puerto 2106).
Desactiva los overrides conflictivos: Ve a "Parámetros avanzados > Rendimiento" y en la sección "Sobreescrituras de módulos", desactiva temporalmente todos los overrides. Si el módulo funciona, reactívalos uno por uno para encontrar el culpable.
Revisa la consola de JavaScript: Abre las herramientas de desarrollador de tu navegador (F12) y ve a la pestaña "Consola". Si ves errores en rojo relacionados con el módulo, anótalos. Normalmente indican qué archivo JS está fallando.

[INFO] Si el módulo usa una API externa (como PayPal o Mailchimp), asegúrate de que tu servidor tenga habilitada la extensión cURL. Puedes verificarlo desde "Parámetros avanzados > Información".

Error 4: Error de base de datos al instalar el módulo

Aparece un mensaje como "Error de SQL" o "Tabla no encontrada". Esto significa que el módulo intenta crear o modificar tablas en la base de datos y algo sale mal.

Causas principales

Permisos de base de datos insuficientes: El usuario de la base de datos no tiene permisos para crear tablas.
Prefijo de tabla incorrecto: El módulo espera un prefijo (ej. ps_) pero tu tienda usa otro (ej. prestashop_).
Base de datos corrupta o llena: La base de datos está dañada o ha alcanzado su límite de tamaño.
Versión de MySQL/MariaDB incompatible: El módulo requiere una versión específica del motor de base de datos.

Soluciones paso a paso

Verifica los permisos del usuario de la BD: Desde phpMyAdmin o la herramienta de tu hosting, asegúrate de que el usuario tenga todos los privilegios (SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, DROP) sobre la base de datos de la tienda.
Comprueba el prefijo de las tablas: Abre la tabla ps_configuration (o como se llame en tu tienda) y busca el valor de _DB_PREFIX_. Debe coincidir con el que usa el módulo. Si no, contacta al desarrollador del módulo.
Repara la base de datos: En phpMyAdmin, selecciona todas las tablas de tu tienda y elige la opción "Reparar tabla". Esto soluciona errores menores de corrupción.
Aumenta el límite de la base de datos: Si tu hosting tiene un límite de tamaño (ej. 1GB), puede que esté llena. Libera espacio eliminando registros antiguos (pedidos, logs) o contacta con tu proveedor para ampliarlo.

[WARNING] Antes de tocar la base de datos, haz siempre una copia de seguridad. Un error puede borrar toda tu tienda. Usa la herramienta de backup de tu hosting o un módulo especializado.

Error 5: El módulo no se actualiza o da error al actualizar

Tienes una versión antigua del módulo y al intentar actualizar, te sale un error. O la actualización se completa pero el módulo deja de funcionar.

Causas principales

Archivos de la versión antigua bloqueados: El servidor no puede sobrescribir los archivos porque están en uso.
Cambios en la estructura de la base de datos: La nueva versión espera tablas o columnas que no existen.
Conflicto con personalizaciones: Si modificaste el código del módulo anterior, la actualización puede romperlo.

Soluciones paso a paso

Desactiva el módulo antes de actualizar: Ve a la lista de módulos, desactívalo y luego intenta la actualización.
Borra la carpeta del módulo antes de subir la nueva versión: Conéctate por FTP, ve a /modules/nombre_del_modulo y elimina toda la carpeta. Luego sube la nueva versión desde el back office o por FTP.
Ejecuta las consultas SQL manualmente: Si el módulo no actualiza la base de datos, contacta al desarrollador y pídele el script SQL de actualización. Ejecútalo desde phpMyAdmin.
Revisa los logs de error: En el back office, ve a "Parámetros avanzados > Logs". Busca errores relacionados con el módulo. Te darán pistas sobre qué falla.

[TIP] Siempre lee las notas de la versión antes de actualizar. A veces el desarrollador indica que hay que hacer pasos manuales (como cambiar una API key).

Error 6: El módulo no aparece en el front office (no se ve en la tienda)

Lo instalaste, lo configuraste, pero en la tienda no se ve por ningún lado. Es frustrante, pero suele ser un problema de posicionamiento o de caché.

Causas principales

El módulo no está enganchado (hook): Los módulos se muestran en zonas concretas (ganchos o hooks). Si no lo has asignado a ningún hook, no se verá.
El hook está deshabilitado: El hook donde debería mostrarse está desactivado en el tema.
El tema no es compatible: Algunos temas no soportan ciertos hooks o los han modificado.

Soluciones paso a paso

Asigna el módulo a un hook: Ve a "Módulos > Gestor de módulos", busca el módulo y haz clic en "Posicionar". Elige un hook visible (por ejemplo, "displayHome" para la página principal, "displayLeftColumn" para la columna izquierda). Guarda los cambios.
Verifica que el hook esté activo: Ve a "Diseño > Posiciones". Busca el hook que elegiste. Asegúrate de que tenga un icono verde (activo). Si está rojo, actívalo.
Prueba con otro hook: Si no se ve, prueba con un hook diferente. Por ejemplo, si es un módulo de banner, prueba "displayTop" o "displayFooter".
Revisa la configuración del tema: Algunos temas permiten ocultar hooks. Ve a la configuración del tema y busca opciones como "Mostrar módulos en la columna izquierda".

[INFO] Si después de todo no se ve, puede que el módulo use un hook que tu tema no tiene. En ese caso, tendrás que editar el archivo header.tpl o footer.tpl de tu tema para añadirlo manualmente. Es un paso avanzado, mejor pide ayuda.

Preguntas frecuentes (FAQ)

¿Por qué mi módulo da error "500 Internal Server Error" al instalarlo?

Es casi siempre un problema de memoria PHP o de compatibilidad de PHP. Aumenta el memory_limit a 256M y verifica que tu versión de PHP sea compatible con el módulo. Si el error persiste, revisa los logs del servidor (suelen estar en la carpeta /logs de tu hosting o en Syspanel, puerto 2106).

¿Cómo puedo saber si un módulo es compatible con mi versión de PrestaShop?

Lee la descripción del módulo en la tienda de módulos o en la web del desarrollador. Debe indicar claramente "Compatible con PrestaShop 1.7.x" o "1.6.x". Si no lo pone, asume que no es compatible. También puedes verificar en "Parámetros avanzados > Información" la versión exacta de tu tienda.

¿Qué hago si el módulo me pide una clave de API y no la tengo?

La clave de API la proporciona el servicio externo (por ejemplo, Mailchimp, Google Analytics, una pasarela de pago). Debes registrarte en ese servicio, crear una clave y pegarla en la configuración del módulo. Si no sabes cómo, busca en Google "[nombre del servicio] obtener API key".

¿Es seguro instalar módulos gratuitos de fuentes no oficiales?

No, nunca. Los módulos gratuitos de foros o sitios de descarga suelen tener puertas traseras, malware o código obsoleto. Siempre descarga módulos de la tienda oficial de PrestaShop o del sitio web del desarrollador reconocido.

¿Puedo instalar un módulo manualmente por FTP?

Sí, es una alternativa cuando la subida desde el back office falla. Descomprime el ZIP en tu ordenador, sube la carpeta resultante a /modules de tu tienda mediante FTP, y luego ve al back office a "Módulos > Gestor de módulos" y haz clic en "Instalar" junto al módulo.

Consejos finales para evitar errores al instalar módulos PrestaShop

Mantén todo actualizado: Tanto PrestaShop como los módulos y el tema deben estar en sus últimas versiones estables.
Haz copias de seguridad antes de cada instalación: Usa la herramienta de backup de tu hosting o un módulo de copias. Si algo sale mal, restauras y listo.
Usa un entorno de pruebas: Si es posible, prueba el módulo en una copia de tu tienda (subdominio o instalación local) antes de ponerlo en producción.
Lee los comentarios y valoraciones: Antes de comprar o instalar un módulo, mira las reseñas. Si muchos reportan errores módulos PrestaShop, mejor busca otra opción.
Contacta al soporte del módulo: Si después de todo sigues con problemas, el desarrollador es tu mejor recurso. Normalmente tienen un sistema de tickets o foro de ayuda.

Recuerda: la mayoría de los problemas al instalar módulos PrestaShop tienen solución. Solo necesitas paciencia, seguir los pasos en orden y no tener miedo a pedir ayuda. ¡Tu tienda online puede estar funcionando perfectamente en minutos!