Cómo activar el modo debug de PrestaShop para ver errores

¿Qué es el modo debug de PrestaShop y por qué lo necesitas?

Cuando tu tienda PrestaShop muestra una pantalla blanca, un error 500 o simplemente no carga, lo más probable es que haya un error de PHP oculto que no ves. Por defecto, PrestaShop oculta estos mensajes para proteger la información interna de tu servidor, pero eso te deja sin pistas para solucionar el problema.

El modo debug PrestaShop (también llamado modo desarrollo o modo depuración) es una funcionalidad que muestra en pantalla todos los errores, advertencias y avisos de PHP que ocurren en tu tienda. En lugar de ver una página en blanco, verás un mensaje descriptivo como "Fatal error: Call to undefined method..." que te indica exactamente qué archivo está fallando y en qué línea.

Activar este modo es el primer paso que cualquier técnico de soporte te pedirá hacer cuando algo falla. Con la información que obtienes, puedes diagnosticar si el problema viene de un módulo incompatible, un tema mal configurado o un archivo corrupto.

Antes de empezar: haz una copia de seguridad

Este es el consejo más importante de todo el artículo. Antes de tocar cualquier archivo de configuración de tu PrestaShop, haz una copia de seguridad completa.

Necesitas respaldar dos cosas:

• Los archivos de tu tienda (la carpeta donde está instalado PrestaShop, normalmente public_html o www).
• La base de datos MySQL (puedes exportarla desde phpMyAdmin o desde el panel de control de tu hosting).

Si algo sale mal durante el proceso, podrás restaurar tu tienda sin perder ventas ni datos de clientes. No lo saltes, aunque solo vayas a cambiar una línea de un archivo.

Método 1: Activar el modo debug desde el archivo config/defines.inc.php

Este es el método más conocido y funciona en todas las versiones de PrestaShop. Es el que recomendamos cuando no tienes acceso al panel de administración o cuando la tienda no carga en absoluto.

Paso a paso

1. Accede a tu hosting mediante FTP o el administrador de archivos de tu panel de control. Si usas Syspanel (el panel de control de tu hosting, que se accede por el puerto 2106), busca la sección "Administrador de archivos" o "Gestor FTP".

2. Navega hasta la carpeta raíz donde está instalado PrestaShop. Normalmente es public_html, htdocs o el nombre de tu dominio.

3. Entra en la carpeta config y busca el archivo llamado defines.inc.php.

4. Descarga una copia de este archivo a tu ordenador como respaldo (por si acaso).

5. Abre el archivo con un editor de texto plano, como el Bloc de notas de Windows o Visual Studio Code. No uses Word ni editores que añadan formato.

6. Busca la siguiente línea de código:

define('_PS_MODE_DEV_', false);

7. Cambia false por true. La línea debe quedar así:

define('_PS_MODE_DEV_', true);

8. Guarda el archivo y súbelo de nuevo al servidor, reemplazando el original.

9. Recarga tu tienda. Ahora deberías ver los errores detallados en pantalla.

Cómo interpretar lo que ves

Cuando el modo debug está activo, verás una página con información técnica. Los elementos clave son:

• El mensaje de error: describe qué ha fallado (por ejemplo, "Class 'Module' not found").
• El archivo afectado: la ruta completa del archivo que genera el error.
• La línea exacta: el número de línea donde se produce el fallo.
• La traza de ejecución (stack trace): la secuencia de llamadas que llevaron al error.

Con esta información, sabrás si el problema está en un tema, un módulo o el núcleo de PrestaShop.

Método 2: Activar el debug desde el panel de administración de PrestaShop

Si tu tienda aún carga el panel de administración, este método es más cómodo y no requiere tocar archivos manualmente.

Pasos para versiones recientes (1.7 y 8.x)

1. Accede a tu panel de administración de PrestaShop (normalmente en tudominio.com/admin1234).

2. Ve al menú Parámetros avanzados en el menú lateral izquierdo.

3. Haz clic en Rendimiento (en algunas versiones aparece como "Rendimiento" o "Performance").

4. Dentro de la página, busca la sección Modo de depuración o Debug mode.

5. Verás un selector con varias opciones:

   • Desactivado (modo producción): no muestra errores.
   • Habilitado (modo desarrollo): muestra errores y advertencias.
   • Habilitado con errores de rendimiento: además de errores, muestra consultas lentas a la base de datos.

6. Selecciona Habilitado y guarda los cambios con el botón "Guardar" de la parte superior.

Para versiones antiguas (1.5 y 1.6)

En estas versiones, la opción se encuentra en Preferencias > Rendimiento. Busca el desplegable llamado "Modo debug" y selecciona "Sí". Guarda los cambios.

[INFO] Si tu PrestaShop es muy antiguo (1.4 o anterior), es probable que no tenga esta opción en el panel. En ese caso, usa el método 1 con el archivo defines.inc.php.

Método 3: Activar el debug mediante el archivo .htaccess (solo para usuarios avanzados)

Este método es útil si no puedes modificar defines.inc.php o si quieres activar el debug solo para tu IP y no para todos los visitantes.

En el archivo .htaccess de la raíz de PrestaShop, puedes añadir estas líneas al principio:

php_value display_errors 1
php_value display_startup_errors 1
php_value error_reporting E_ALL

Después de añadirlas, guarda y sube el archivo. Recarga tu tienda y verás los errores.

[WARNING] Este método solo funciona si tu servidor permite directivas php_value en .htaccess. En algunos hosts compartidos, esto está deshabilitado por seguridad. Si no funciona, vuelve al método 1.

¿Cuánto tiempo debo dejar el modo debug activado?

El modo debug no debe quedarse activo de forma permanente. Cuando está habilitado, muestra información sensible de tu servidor (rutas absolutas, configuración de base de datos, versiones de PHP) que un atacante podría aprovechar.

La recomendación es:

1. Activa el modo debug solo cuando necesites diagnosticar un error.
2. Anota o captura el mensaje de error que aparece.
3. Desactiva el modo debug inmediatamente después de solucionar el problema.

Para desactivarlo, simplemente invierte el proceso: cambia true por false en el archivo, o selecciona "Desactivado" en el panel de administración.

Errores comunes que verás con el debug activado

Estos son los errores más frecuentes que aparecen al activar el modo debug en PrestaShop:

Error de memoria (Memory limit)

Fatal error: Allowed memory size of 134217728 bytes exhausted

Este error indica que PHP necesita más memoria de la que tiene asignada. Puedes solucionarlo aumentando el límite en el archivo config/defines.inc.php o en php.ini:

ini_set('memory_limit', '256M');

Error de clase no encontrada

Fatal error: Class 'SomeModule' not found in /ruta/al/archivo.php

Suele ocurrir cuando un módulo no se ha subido correctamente o cuando hay una incompatibilidad con la versión de PrestaShop. Revisa que el módulo esté en la carpeta modules y que su nombre coincida exactamente.

Error de conexión con la base de datos

Connection to MySQL server failed

Revisa los datos de conexión en el archivo config/settings.inc.php. Asegúrate de que el usuario y la contraseña de MySQL sean correctos y que el servidor de base de datos esté en línea.

Consejos adicionales para el diagnóstico

Activa el log de errores de PHP

Además del modo debug, puedes configurar PHP para que guarde los errores en un archivo de registro. Esto es útil si el error ocurre durante un proceso que no puedes reproducir manualmente.

En el archivo config/defines.inc.php, añade estas líneas justo debajo de la línea de _PS_MODE_DEV_:

ini_set('log_errors', 1);
ini_set('error_log', dirname(__FILE__) . '/../var/logs/php_errors.log');

Después de añadirlas, crea la carpeta var/logs si no existe y asegúrate de que tenga permisos de escritura (755 o 775).

Comprueba los logs de PrestaShop

PrestaShop guarda sus propios registros de errores en la carpeta var/logs (en versiones 1.7 y 8.x) o en log/ (en versiones 1.6). Revisa estos archivos si el error no aparece en pantalla.

Usa herramientas de terceros

Si el modo debug no te da suficiente información, puedes instalar un módulo de diagnóstico como "PrestaShop Error Viewer" o usar las herramientas de desarrollo del navegador (F12 > pestaña Consola) para ver errores de JavaScript que también pueden causar problemas visuales.

Preguntas frecuentes sobre el modo debug de PrestaShop

¿Es seguro activar el modo debug en una tienda en producción?

No es recomendable dejarlo activo permanentemente porque expone información sensible. Actívalo solo durante el diagnóstico y desactívalo al terminar. Si necesitas mantenerlo activo por un tiempo, hazlo en un entorno de pruebas o en horario de bajo tráfico.

¿El modo debug afecta al rendimiento de mi tienda?

Sí, ligeramente. Mostrar errores en pantalla consume más recursos y ralentiza las páginas. Además, en modo debug se desactivan ciertas optimizaciones de caché. Por eso solo debe usarse temporalmente.

¿Qué hago si mi tienda se rompe al activar el debug?

Si al activar el modo debug aparece un error que antes no veías, no te asustes. El error ya existía, solo que estaba oculto. Usa la información que ahora ves para solucionarlo. Si el problema es que la tienda no carga ni con el debug activo, restaura la copia de seguridad que hiciste al principio.

¿Puedo activar el debug sin acceso FTP?

Sí, si tienes acceso al panel de administración, puedes usar el método 2. Si no tienes acceso al panel ni por FTP, contacta con tu proveedor de hosting. Si usas Syspanel (puerto 2106), es posible que tengan una opción de "Modo mantenimiento" o "Debug" en el gestor de archivos.

¿El modo debug muestra errores de SQL?

Sí, cuando está activo, PrestaShop muestra también errores de base de datos. Verás mensajes como "Duplicate entry" o "Table 'ps_orders' doesn't exist" que te ayudarán a identificar problemas en las consultas SQL.

Resumen final: flujo de trabajo recomendado

Cuando tu tienda dé un error, sigue este proceso:

1. Haz una copia de seguridad de archivos y base de datos.
2. Activa el modo debug con cualquiera de los métodos explicados.
3. Identifica el error: anota el mensaje, el archivo y la línea.
4. Busca la solución en foros oficiales o consulta con tu soporte técnico.
5. Aplica la corrección (actualizar módulo, modificar configuración, etc.).
6. Desactiva el modo debug para volver al modo producción.
7. Verifica que la tienda funciona correctamente en modo normal.

El modo debug es la herramienta más poderosa que tienes para solucionar errores en PrestaShop. Con estos pasos, podrás diagnosticar cualquier problema por ti mismo y ahorrar tiempo y dinero en soporte técnico. Recuerda siempre trabajar con copias de seguridad y desactivar el modo debug cuando termines.