Solucionar el error 'Fatal error: Class not found' en PrestaShop

¡Hola! Si has llegado hasta aquí buscando cómo solucionar el error PrestaShop class not found, estás en el lugar correcto. Este es uno de los avisos más temidos por los dueños de tiendas online, pero no te preocupes: en la gran mayoría de los casos tiene una solución sencilla que puedes aplicar tú mismo, sin necesidad de ser un programador experto.

Cuando ves un mensaje como Fatal error: Class not found en la pantalla de tu tienda o en el panel de administración, la tienda puede quedarse bloqueada o mostrar una página en blanco. Esto asusta, lo sé. Pero vamos a desgranar qué significa, por qué ocurre y, lo más importante, cómo arreglarlo paso a paso.

En esta guía completa, pensada para principiantes, te explicaré las causas más comunes y las soluciones prácticas para que tu PrestaShop vuelva a funcionar en pocos minutos. Vamos a ello.

¿Qué significa exactamente "Fatal error: Class not found"?

Antes de lanzarnos a arreglar nada, es fundamental entender qué te está diciendo el sistema. PrestaShop está construido sobre un lenguaje de programación llamado PHP, que organiza su código en "clases".

Piensa en una clase como un molde o una plantilla que define cómo funciona una parte de la tienda (por ejemplo, la clase Product gestiona los productos, la clase Cart gestiona el carrito, etc.). Cuando PHP intenta usar una de estas clases y no la encuentra en la ubicación esperada, se detiene en seco y muestra el error Fatal error: Class not found.

Este error suele aparecer acompañado de más información, como la ruta del archivo que lo provoca o el nombre de la clase que falta. Por ejemplo:

Fatal error: Class 'Module' not found in /home/.../config/config.inc.php on line 87

Esa línea extra es oro puro, porque nos dice exactamente qué clase busca y en qué archivo. Anota ese dato, nos será muy útil.

Causas principales del error "Class not found" en PrestaShop

Este fallo no aparece por arte de magia. Casi siempre responde a una de estas cinco situaciones:

1. Actualización incompleta o fallida de PrestaShop, un módulo o un tema

Es la causa número uno. Si estabas actualizando la tienda, un módulo o el tema y el proceso se interrumpió (por un corte de conexión, un timeout del servidor o un error de permisos), es muy probable que algunos archivos se hayan quedado a medias. Faltan clases nuevas o las rutas han cambiado, y el sistema no las encuentra.

2. Archivos corruptos o incompletos tras una subida por FTP

Si has subido archivos manualmente mediante un cliente FTP (como FileZilla) y la transferencia se cortó o se hizo en el directorio equivocado, puedes haber sobrescrito archivos importantes o haber dejado otros sin subir. Esto provoca que el sistema busque clases que no están presentes.

3. Problemas de permisos de archivos y carpetas

Los archivos de tu tienda tienen que tener permisos específicos para que el servidor pueda leerlos y ejecutarlos. Si estos permisos son incorrectos (por ejemplo, muy restrictivos), PHP no puede "ver" el archivo de la clase y, por tanto, no puede cargarla. Esto suele pasar tras mover la tienda de servidor o usar ciertos gestores de archivos.

4. Conflictos entre módulos o temas incompatibles

A veces, instalar un módulo nuevo que no es compatible con tu versión de PrestaShop o con otro módulo existente puede generar conflictos. Al activarlo, intenta cargar una clase que no existe o que está definida en otro lugar, rompiendo todo el sistema.

5. Errores en el archivo de configuración o en la caché

PrestaShop guarda una caché de sus clases y configuraciones para ir más rápido. Si esa caché se corrompe, puede intentar cargar una clase desde una ruta antigua o incorrecta, provocando el error. También un archivo settings.inc.php con rutas mal configuradas puede ser el culpable.

Cómo solucionar el error "Class not found": Guía paso a paso

Ahora sí, vamos a la acción. Te propongo una serie de soluciones ordenadas de la más simple y segura a la más compleja. Te recomiendo probarlas en este orden, ya que así resolverás el problema en el 90% de los casos sin tocar nada delicado.

Paso 1: La solución mágica – Borrar la caché

Aunque parezca mentira, muchos de estos errores se solucionan simplemente vaciando la caché de PrestaShop. Una caché corrupta o desactualizada es la causa de muchísimos problemas "fantasma".

Para hacerlo, tienes dos opciones:

Opción A: Desde el Panel de Administración (si puedes acceder)

1. Ve a Parámetros avanzados > Rendimiento.
2. Busca la opción "Vaciar la caché" y haz clic en el botón correspondiente.
3. También puedes forzar la regeneración de las plantillas en "Plantillas" marcando la casilla "Forzar la compilación" y guardando.
4. Vuelve a intentar acceder a tu tienda.

Opción B: De forma manual (si no puedes acceder al panel)

Si el error te impide entrar al back-office, tendrás que borrar la caché manualmente desde el servidor.

1. Accede a tu panel de control de hosting o a Syspanel (recuerda, el puerto de acceso es el 2106).
2. Abre el Administrador de archivos.
3. Navega hasta la carpeta raíz de tu PrestaShop (donde están las carpetas admin, config, classes, etc.).
4. Dentro, busca la carpeta var/cache (en versiones antiguas de PrestaShop 1.6, era la carpeta cache).
5. Dentro de var/cache, verás una carpeta llamada dev y otra prod. Entra en la que corresponda a tu entorno (normalmente prod) y borra todo su contenido (archivos y carpetas).
6. Si no encuentras la carpeta, crea una en la raíz llamada cache (si no existe) y dentro de ella, crea una subcarpeta llamada tmp. Esto fuerza a PrestaShop a regenerar la caché desde cero.

[TIP] Si usas Syspanel (puerto 2106), el administrador de archivos es muy visual. Simplemente selecciona todos los archivos dentro de prod y haz clic en "Eliminar".

Paso 2: Revisar y corregir los permisos de archivos y carpetas

Si borrar la caché no ha funcionado, el siguiente paso es asegurarnos de que los archivos tienen los permisos correctos.

Los permisos ideales para PrestaShop son:

• Carpetas (directorios): 755
• Archivos: 644

Para cambiarlos:

1. Accede de nuevo a tu Syspanel (puerto 2106) o a tu cliente FTP.
2. Ve a la raíz de tu instalación de PrestaShop.
3. Selecciona todas las carpetas y archivos (Ctrl+A o Cmd+A).
4. Busca la opción "Permisos" o "CHMOD".
5. Introduce el valor 755 para las carpetas y 644 para los archivos. Algunos gestores te permiten aplicar la opción "recursivamente" (a todas las subcarpetas). Asegúrate de marcarla.
6. Guarda los cambios y espera a que termine. Luego, prueba a cargar tu tienda.

[WARNING] No cambies los permisos a 777 (todos los permisos), ya que es un grave riesgo de seguridad. Usa siempre 755 y 644.

Paso 3: Desactivar el modo "No borrar" y regenerar el autoload

PrestaShop tiene un archivo llamado autoload.php que registra todas las clases disponibles. A veces, este archivo se daña o no se actualiza.

1. Con un editor de texto plano (como el Bloc de notas o Notepad++), abre el archivo config/autoload.php de tu instalación.
2. Busca la línea que dice public static $index = array( o similar.
3. Justo debajo, o al principio del array, busca una entrada que diga 'classes' => ... o 'controllers' => ....
4. Lo que haremos es forzar que se regenere. La forma más fácil es borrar el contenido del array que está entre array( y );. No borres la estructura, solo el contenido.

[INFO] Esto suena aterrador, pero es un truco muy conocido. Al dejar el array vacío, PrestaShop se ve obligado a escanear todas sus carpetas y reconstruir el índice de clases automáticamente. Es como un "reinicio" del registro de clases.

Paso 4: Reinstalar el módulo o tema conflictivo

Si el error menciona el nombre de un módulo específico (por ejemplo, Class 'MyModule' not found), el problema está en ese módulo.

1. Accede al panel de administración de PrestaShop.
2. Ve a Módulos > Módulos y servicios.
3. Busca el módulo problemático.
4. Si puedes, intenta desactivarlo primero. Si no puedes, tendrás que hacerlo manualmente.
5. Para desactivarlo manualmente, renombra la carpeta del módulo en el servidor (dentro de /modules). Por ejemplo, cambia mimodulo a mimodulo_off. Esto lo desactiva sin desinstalarlo.
6. Si la tienda vuelve a funcionar, el problema era ese módulo. Entonces, puedes intentar reinstalarlo (subiendo una copia limpia) o ponerte en contacto con el desarrollador.

Lo mismo aplica para el tema. Si el error menciona una clase del tema (como Class 'ThemeClass' not found), ve a Diseño > Tema y logotipo y cambia a un tema por defecto temporalmente (como el clásico) para confirmar.

Paso 5: Restaurar una copia de seguridad

Si has llegado hasta aquí y nada funciona, la solución más drástica pero efectiva es restaurar una copia de seguridad de tu tienda de un momento en el que todo funcionaba correctamente.

1. Accede a tu Syspanel (puerto 2106) y busca la sección de "Copias de seguridad" o "Backups".
2. Localiza una copia de seguridad reciente (de antes de que empezara el error).
3. Restaura tanto los archivos como la base de datos.
4. Ten en cuenta que perderás los cambios realizados desde la fecha de la copia.

[WARNING] Restaurar una copia de seguridad sobrescribirá toda tu tienda. Asegúrate de que es la última opción y de que has intentado todo lo demás antes.

Cómo prevenir este error en el futuro

Una vez que hayas solucionado el problema, es hora de blindar tu tienda para que no vuelva a ocurrir. Aquí tienes algunos buenos hábitos:

• Siempre haz copias de seguridad completas antes de actualizar PrestaShop, módulos o temas.
• Actualiza tu tienda, módulos y temas a las últimas versiones estables. Las actualizaciones corrigen errores y mejoran la compatibilidad.
• Descarga módulos y temas solo de fuentes oficiales (Addons de PrestaShop o desarrolladores de confianza). Los módulos piratas o mal codificados son una fuente inagotable de errores.
• No interrumpas nunca un proceso de actualización. Asegúrate de tener una conexión a internet estable y de que el proceso de actualización no tenga un límite de tiempo demasiado corto en tu servidor.
• Mantén los permisos de archivos correctos (755 para carpetas, 644 para archivos) de forma regular.

Preguntas frecuentes (FAQ)

¿Por qué veo el error solo en el back-office y no en la tienda?

Esto es común. El panel de administración y la tienda usan diferentes controladores y clases. Puede que el error esté en un módulo que solo se carga en el back-office o en un tema de administración personalizado. Aplica las mismas soluciones, pero céntrate en los archivos relacionados con el panel de administración.

¿Qué hago si el error no menciona ninguna clase específica?

A veces el error es genérico. En ese caso, empieza siempre por borrar la caché y revisar los permisos. Si no funciona, revisa el archivo config/settings.inc.php y asegúrate de que las rutas (_PS_ROOT_DIR_) apuntan a la carpeta correcta de tu instalación.

¿Puedo solucionar este error editando el archivo .htaccess?

En la mayoría de los casos, el error "Class not found" no está relacionado con el .htaccess. Ese archivo gestiona las redirecciones y URLs. Sin embargo, si el error ocurre solo en páginas específicas, regenerar el .htaccess desde Parámetros avanzados > Rendimiento (botón "Generar .htaccess") puede ayudar a descartar problemas de URL amigables.

¿Es seguro borrar la carpeta var/cache?

Sí, es completamente seguro. Esa carpeta solo contiene archivos temporales que PrestaShop regenera automáticamente. Borrarla es una de las primeras acciones recomendadas por el propio equipo de PrestaShop para solucionar errores.

¿Y si nada de esto funciona?

Si has probado todos los pasos anteriores sin éxito, el problema puede ser más profundo (un error en el código de un módulo muy complejo, un conflicto de base de datos, etc.). En ese caso, te recomiendo encarecidamente que contactes con el soporte técnico de tu hosting o con un desarrollador especializado en PrestaShop. Es mejor pagar por una solución profesional que perder horas (y ventas) intentando arreglarlo a ciegas.

Espero que esta guía te haya sido de gran ayuda. Como ves, solucionar error PrestaShop no tiene por qué ser una pesadilla. Con paciencia y siguiendo estos pasos, podrás arreglar clase no encontrada y tener tu tienda online operativa de nuevo en muy poco tiempo. ¡Mucha suerte!