El fallo de autoload en módulos de PrestaShop ocurre cuando el cargador automático de PHP no encuentra una clase requerida por una dependencia externa instalada con Composer. En la gran mayoría de casos, esto se resuelve ejecutando un volcado del cargador optimizado o reinstalando el directorio vendor directamente dentro de la carpeta del módulo. Si tras subir el archivo ZIP la tienda se queda en blanco, te encuentras ante un error 500 en PrestaShop tras instalar o actualizar un módulo provocado por rutas desfasadas o paquetes ausentes.
Qué significa el error
El mensaje suele manifestarse como Fatal error: Uncaught Error: Class 'Nombre\Espacio\Clase' not found o bien require(): Failed opening required '/modules/nombremodulo/vendor/autoload.php'. Aparece en el momento exacto en el que intentas subir el módulo desde el panel de administración, cuando haces clic en Instalar, o inmediatamente después de vaciar la caché de PrestaShop.
Afecta principalmente a desarrolladores y administradores que trabajan con PrestaShop 1.7 y PrestaShop 8 sobre versiones de PHP 7.4, 8.1 o 8.2, al utilizar extensiones modernas empaquetadas sin sus dependencias compiladas o descargadas desde repositorios Git sin haber ejecutado Composer previamente.
Causas más habituales
- El directorio vendor no existe en el paquete: El desarrollador ha excluido la carpeta
vendor/mediante.gitignoreal empaquetar el ZIP del módulo. - Falta de regeneración del autoload tras mover archivos: Las rutas internas de
autoload_psr4.phpoautoload_classmap.phpapuntan a directorios absolutos del entorno de desarrollo original. - Incompatibilidad entre versiones de PHP: Las dependencias del módulo se generaron con una versión de PHP (por ejemplo, 8.2) que exige tipados incompatibles con el entorno del servidor (por ejemplo, PHP 7.4).
- Conflicto con dependencias globales del core: El módulo y el núcleo de PrestaShop requieren la misma librería externa pero con versiones incompatibles entre sí (conflictos con paquetes de Symfony, Guzzle o PhpSpreadsheet).
- Permisos incorrectos en el sistema de archivos: El usuario del servidor web (
www-dataoapache) no puede leer los archivos dentro demodules/minombremodulo/vendor/.
Antes de empezar
Antes de aplicar cualquier cambio por terminal o FTP en una tienda en producción, ten en cuenta los siguientes requisitos:
- Realiza una copia de seguridad completa de la base de datos y de la carpeta
modules/de tu PrestaShop. - Asegúrate de contar con acceso SSH al servidor y Composer 2 instalado globalmente. Puedes verificarlo con
composer --version. - Comprueba la versión activa de PHP en tu terminal ejecutando
php -vy valida que coincide con la que utiliza tu servidor web para PrestaShop. - Si la tienda se encuentra bloqueada por completo y no puedes acceder al back-office, revisa nuestra guía para solucionar el error 500 en un módulo de PrestaShop paso a paso desactivando la extensión mediante la base de datos o renombrando la carpeta temporalmente.
Solución 1: Regenerar el autoloader de Composer en el módulo
Esta es la intervención más limpia y segura si la carpeta vendor ya existe dentro del módulo pero el mapa de clases no detecta los nuevos archivos o contiene rutas corruptas.
- Accede a tu servidor mediante SSH.
- Navega hasta el directorio raíz del módulo con el comando:
cd /var/www/html/modules/nombre_del_modulo - Verifica que existe el archivo
composer.jsonen la raíz de dicho directorio. - Ejecuta el volcado del cargador optimizado:
composer dump-autoload -o --no-dev - Ajusta los permisos de usuario y grupo para que el servidor web pueda leer los nuevos archivos generados:
chown -R www-data:www-data vendor/ - Accede al panel de administración de PrestaShop y vacía la caché desde Parámetros Avanzados > Rendimiento > Borrar la caché.
Por qué funciona: La bandera -o (u --optimize) convierte las reglas de carga PSR-4 y PSR-0 en un mapa de clases directo dentro de vendor/composer/autoload_classmap.php. Esto hace que PHP encuentre la ubicación exacta del archivo sin realizar búsquedas en el sistema de archivos, ignorando cachés desactualizadas.
Solución 2: Reinstalación completa de dependencias de producción
Si faltan paquetes en el directorio vendor o se añadieron manualmente archivos que han roto las dependencias cruzadas, la mejor opción es descargar de nuevo los paquetes definidos en el bloqueo.
- Conéctate por SSH y accede a la carpeta del módulo:
cd /var/www/html/modules/nombre_del_modulo - Atención: Haz un respaldo previo del directorio si contenía modificaciones personalizadas:
cp -r vendor vendor_backup - Elimina la carpeta de dependencias dañada:
rm -rf vendor - Instala las dependencias respetando el archivo
composer.lockpara asegurar versiones idénticas:composer install --no-dev --optimize-autoloader - Si el comando anterior falla por conflicto de versiones de PHP con la CLI, fuerza la compatibilidad con el entorno del core:
composer install --no-dev --optimize-autoloader --ignore-platform-reqs - Restaura los permisos para el servidor web:
chown -R www-data:www-data .
Por qué funciona: Al borrar vendor y ejecutar composer install, Composer reconstruye el árbol de dependencias exacto que el autor del módulo definió en composer.lock, eliminando posibles ficheros corruptos o descargados a medias.
Solución 3: Prefijar dependencias con PHP-Scoper para evitar colisiones con el core
Cuando un módulo requiere una versión distinta de una librería que ya usa PrestaShop (por ejemplo, GuzzleHttp o Symfony Components), el autoloader de PrestaShop carga la versión global antes que la del módulo, desatando errores fatales. La documentación oficial de Composer recomienda aislar los espacios de nombres en arquitecturas modulares.
- Descarga el código del módulo a tu entorno local de desarrollo.
- Abre el archivo principal del módulo (ejemplo:
nombre_del_modulo.php). - Verifica cómo se incluye el autoloader. Debe llamar exclusivamente al suyo:
if (file_exists(__DIR__ . '/vendor/autoload.php')) { require_once __DIR__ . '/vendor/autoload.php'; } - Si existe una colisión de dependencias directa, debes encapsular las librerías bajo tu propio namespace. Instala PHP-Scoper en tu máquina local:
composer global require humbug/php-scoper - Genera el prefijo de clases en tu archivo
scoper.inc.phpy compila las dependencias prefijadas hacia una carpeta comobuild/vendor. - Apunta el
require_oncedel módulo a ese nuevo directorio aislado y sube de nuevo el paquete.
Por qué funciona: Al modificar los nombres de las clases (por ejemplo, renombrando GuzzleHttp\Client a MiModulo\Vendor\GuzzleHttp\Client), PrestaShop no confunde la versión requerida por el módulo con la versión interna que el núcleo tiene cargada en memoria.
Solución 4: Configuración manual del autoload en el archivo composer.json
En módulos personalizados o de código abierto poco mantenidos, es común que las clases del propio módulo (controladores, servicios o modelos) no estén contempladas dentro de la directiva de carga automática de Composer.
- Abre con un editor el archivo
modules/nombre_del_modulo/composer.json. - Localiza la sección
autoload. Si no existe, añádela asegurando la correspondencia exacta entre mayúsculas y minúsculas con el directorio del sistema:{ "name": "proveedor/nombre_del_modulo", "autoload": { "psr-4": { "MiModulo\\": "src/" } }, "config": { "prepend-autoloader": false } } - Fíjate en el parámetro
"prepend-autoloader": false. Añádelo dentro deconfigpara que el módulo no se imponga al cargador principal de PrestaShop. - Guarda los cambios y ejecuta en la terminal dentro del módulo:
composer dump-autoload -o - Elimina la caché manual de PrestaShop borrando los archivos temporales:
rm -rf /var/www/html/var/cache/prod/* /var/www/html/var/cache/dev/*
Por qué funciona: Definir correctamente el estándar PSR-4 en el composer.json permite que el autoloader sepa en qué subcarpeta buscar cada clase instanciada con un determinado espacio de nombres, impidiendo que el motor de PHP lance una excepción de archivo no encontrado. Si tras esto el instalador sigue rechazando el módulo, consulta los pasos en cómo solucionar el error de módulos que no se pueden instalar en PrestaShop para revisar restricciones a nivel de base de datos.
Cómo comprobar que se ha solucionado
Para comprobar que el módulo carga correctamente, sigue estos pasos:
- Entra en el back-office de PrestaShop y accede a Módulos > Module Manager. El módulo debe figurar activo sin advertencias ni banners en rojo.
- Visita la página de configuración del módulo en el panel de control. Si la vista se renderiza sin errores, las dependencias internas funcionan.
- Comprueba los logs del sistema en Parámetros Avanzados > Registros/Logs para verificar que no se registren alertas con severidad 3 o 4 vinculadas al módulo.
- Si el módulo tiene impacto en el front-office (como un transportista, pasarela de pago o bloque visual), añade un producto al carrito y llega hasta el paso final para confirmar que no se produce ninguna interrupción.
Si nada de lo anterior funciona
Si el autoloader sigue fallando después de regenerarlo, el problema puede deberse a discrepancias severas del entorno o errores en tiempo de ejecución. Activa el modo depuración de PrestaShop cambiando el valor en el archivo config/defines.inc.php:
define('_PS_MODE_DEV_', true);Carga de nuevo la página para ver la traza completa (Stack Trace). Fíjate en el primer archivo que produce la excepción: si pertenece a var/cache/, elimina esa carpeta completamente. Si el error apunta a una función de PHP deprecada (como métodos de Reflection en PHP 8.1), el módulo no es compatible con la versión de PHP configurada en tu hosting y deberás solicitar una actualización al desarrollador o ajustar la versión de PHP desde el panel de control de tu servidor.
Preguntas frecuentes
¿Por qué no puedo simplemente subir la carpeta vendor por FTP?
Puedes subirla por FTP, pero es muy frecuente que fallen archivos debido a transferencias incompletas o conversiones en el modo de transferencia (ASCII en lugar de Binario). Además, el archivo autoload_classmap.php suele contener rutas absolutas que dejan de coincidir si se generaron en un ordenador con Windows y el servidor usa Linux.
¿Afecta la versión de Composer (v1 vs v2) a PrestaShop?
PrestaShop 1.7.x utiliza internamente dependencias preparadas en su mayoría para Composer 1 o transicionales a Composer 2, mientras que PrestaShop 8 requiere Composer 2 de forma nativa. Si generas el autoloader de un módulo con Composer 2 para una tienda en PrestaShop 1.7 con PHP 7.1 o 7.2, la plataforma puede arrojar incompatibilidades por directivas no reconocidas.
¿Es seguro borrar la carpeta var/cache en PrestaShop?
Sí, es totalmente seguro. PrestaShop regenera automáticamente todos los contenedores de dependencias y cachés de Symfony y Smarty la próxima vez que cualquier usuario o administrador visita la tienda. Es un procedimiento estándar cuando se modifica la estructura de clases de cualquier módulo.
¿Qué significa el parámetro prepend-autoloader en Composer?
Por defecto, cuando un módulo carga su autoload.php, Composer se coloca al principio de la lista de cargadores de PHP. Si se define "prepend-autoloader": false en el archivo composer.json, el cargador del módulo se añade al final de la cola, permitiendo que el núcleo de PrestaShop resuelva primero sus propias dependencias y evitando conflictos graves de versiones.
