PrestaShop: Cómo activar y configurar el modo debug para resolver errores

¿Qué es el modo debug de PrestaShop y para qué sirve?

Cuando tu tienda online empieza a dar problemas, como una pantalla en blanco, un error 500 o mensajes crípticos, es normal sentirse abrumado. La buena noticia es que PrestaShop incluye una herramienta oculta muy potente para diagnosticar estos fallos: el modo debug (o modo depuración).

Activar el prestashop modo debug es como encender una linterna dentro de una habitación oscura. Te permite ver exactamente qué está fallando, en qué archivo y en qué línea de código. Sin esta herramienta, solo verías una página en blanco o un error genérico, lo que hace casi imposible resolver el problema.

En este artículo, te explicaré paso a paso cómo activar debug prestashop, cómo configurarlo correctamente y, lo más importante, cómo interpretar la información que te muestra para ver errores prestashop de forma clara y efectiva. No necesitas ser un programador experto; solo seguir estas instrucciones sencillas.

¿Cuándo necesitas activar el modo debug?

Hay varias situaciones comunes en las que configurar debug prestashop se vuelve imprescindible:

• Pantalla blanca o error 500: Es el síntoma más común. La tienda no carga y no sabes por qué.
• Errores al instalar un módulo o tema: A veces, una extensión incompatible rompe toda la tienda.
• Problemas con el carrito de compra o el pago: Fallos en la lógica de negocio que solo muestran un mensaje genérico.
• Errores de base de datos: Como "table not found" o "connection refused".
• Desarrollo y pruebas: Si estás creando una tienda, es fundamental tener el debug activado para corregir errores sobre la marcha.

[WARNING]
Activar el modo debug muestra información sensible de tu servidor (rutas de archivos, consultas SQL, etc.). Nunca lo dejes activado en una tienda en producción (operativa), ya que expones datos internos a los visitantes. Actívalo solo para diagnosticar y desactívalo al terminar.

Método 1: Activar el modo debug editando el archivo define.inc.php (Recomendado)

Este es el método más fiable y funciona en todas las versiones de PrestaShop. El archivo que debes modificar se llama defines.inc.php y se encuentra en la carpeta config de tu instalación.

Paso 1: Accede a tu hosting o servidor

Primero, necesitas acceder a los archivos de tu tienda. Puedes hacerlo de dos formas:

1. A través del Panel de Control del Hosting (Syspanel): Si tu hosting usa Syspanel, inicia sesión en https://tu-dominio.com:2106 o la URL que te hayan proporcionado. Dentro del panel, busca la sección "Administrador de archivos" o "Gestor de archivos".
2. A través de FTP: Usa un cliente FTP como FileZilla y conéctate con las credenciales que te dio tu proveedor de hosting.

[TIP]
Si no sabes cuál es la ruta exacta de tu tienda, busca la carpeta donde se encuentran las subcarpetas admin, config, var, etc. Normalmente es public_html o htdocs.

Paso 2: Localiza y edita el archivo defines.inc.php

Una vez dentro del administrador de archivos, navega hasta la carpeta config y busca el archivo defines.inc.php.

Haz clic derecho sobre él y selecciona "Editar" o "Edit". Se abrirá un editor de texto dentro del propio panel.

Paso 3: Modifica el valor de PS_MODE_DEV

Dentro del archivo, busca la siguiente línea:

define('_PS_MODE_DEV_', false);

Esta línea está controlada por una constante de PHP que le dice a PrestaShop si debe mostrar o no los errores. Para activar el modo debug, debes cambiar false por true.

El resultado debe ser este:

define('_PS_MODE_DEV_', true);

Paso 4: Guarda los cambios

Guarda el archivo y cierra el editor. Ahora, cuando recargues tu tienda, en lugar de una pantalla en blanco, deberías ver una página con el error detallado, incluyendo la ruta del archivo y la línea exacta del problema.

[INFO]
Si además de ver el error en pantalla quieres que se guarde en un archivo de registro, busca la línea define('_PS_DEBUG_SQL_', false); y cámbiala a true. Esto guardará las consultas SQL en un archivo de log, lo cual es muy útil para problemas de base de datos.

Método 2: Activar el modo debug desde el panel de administración (Versiones modernas)

En versiones recientes de PrestaShop (1.7 y 8.x), existe una forma más visual y rápida de activar el debug, sin tocar código directamente.

Paso 1: Accede a tu panel de administración

Entra en la URL de tu administrador (por ejemplo, tutienda.com/admin123).

Paso 2: Ve a Parámetros Avanzados

En el menú lateral izquierdo, busca la sección "Parámetros Avanzados" o "Advanced Parameters". Dentro de ella, haz clic en "Rendimiento" o "Performance".

Paso 3: Configura el modo de depuración

Busca una opción llamada "Modo de depuración" o "Debug mode". Verás un selector con varias opciones:

• Desactivado (Disabled): La opción por defecto.
• No incluir el rendimiento (Without performance): Muestra errores pero no la información de rendimiento (tiempo de carga, consultas SQL, etc.).
• Incluir el rendimiento (With performance): Muestra errores y también información detallada de rendimiento, ideal para desarrolladores.

Selecciona la opción que necesites. Te recomiendo "No incluir el rendimiento" para la mayoría de los casos, ya que es más limpio y fácil de leer.

Paso 4: Guarda los cambios

Haz clic en "Guardar" o "Save". El sistema recargará y, a partir de ese momento, los errores se mostrarán en pantalla.

[WARNING]
Si tu tienda está completamente rota y no puedes acceder al panel de administración, este método no te servirá. En ese caso, tendrás que usar el Método 1 (editar el archivo manualmente).

¿Cómo interpretar los errores que muestra el modo debug?

Una vez que has activado debug prestashop, verás una pantalla que puede parecer abrumadora al principio, pero es muy lógica. Vamos a desglosarla:

• El mensaje principal: Suele comenzar con la palabra "Error" o "Exception". Te dice qué ha fallado. Por ejemplo: "Class 'Product' not found".
• La ruta del archivo: Te indica en qué archivo se ha producido el error. Por ejemplo: /home/tudominio/public_html/modules/mimodulo/mimodulo.php.
• El número de línea: Es la línea exacta del archivo donde se ha detectado el fallo. Ejemplo: on line 42.
• El "Stack Trace" (Traza de pila): Es una lista de todas las llamadas a funciones que se han ejecutado antes del error. Esto te ayuda a rastrear el origen del problema. No te asustes, normalmente el error está en la primera o segunda línea de esta lista.

Ejemplo práctico de un error común

Imagina que ves esto:

[ERROR] Uncaught Error: Call to undefined function get_header() in /home/.../themes/mitema/header.tpl:12

¿Qué significa? Que en el archivo header.tpl de tu tema, en la línea 12, se está intentando llamar a una función llamada get_header() que no existe. Esto suele pasar cuando un tema o módulo está desactualizado o es incompatible con tu versión de PrestaShop.

¿Qué haces? Ahora sabes exactamente qué archivo tocar. Puedes abrir header.tpl, buscar la línea 12 y corregir la función o, si es un módulo, actualizarlo o desinstalarlo.

Errores comunes y sus soluciones rápidas

Aquí te dejo una lista de los errores más frecuentes que verás al ver errores prestashop con el debug y cómo solucionarlos:

1. Error de conexión a la base de datos

• Mensaje: Link to database cannot be established o SQLSTATE[HY000] [1045] Access denied for user.
• Causa: Las credenciales de la base de datos son incorrectas o el servidor de base de datos está caído.
• Solución: Revisa el archivo app/config/parameters.php y verifica que el usuario, contraseña y nombre de la base de datos sean correctos. Si no has cambiado nada, contacta con tu proveedor de hosting.

2. Error de memoria agotada

• Mensaje: Allowed memory size of X bytes exhausted.
• Causa: Tu tienda necesita más memoria PHP de la que tiene asignada.
• Solución: Aumenta el límite de memoria. Puedes hacerlo en el archivo config/defines.inc.php añadiendo ini_set('memory_limit', '256M'); al principio, o desde el panel de control del hosting en la configuración de PHP.

3. Error de clase no encontrada

• Mensaje: Class 'X' not found.
• Causa: Un módulo o tema intenta usar una clase que no existe o no se ha cargado.
• Solución: Si es un módulo, intenta desactivarlo desde la base de datos (mediante phpMyAdmin) o renombra la carpeta del módulo en /modules/. Si es un tema, cambia al tema por defecto.

4. Error de sintaxis en un archivo

• Mensaje: Parse error: syntax error, unexpected '}'.
• Causa: Hay un error de escritura en un archivo PHP.
• Solución: Abre el archivo indicado y revisa la línea que marca el error. Busca llaves sin cerrar, comillas mal puestas o puntos y comas olvidados.

¿Qué hacer cuando el error no aparece ni con el modo debug?

A veces, el modo debug no es suficiente porque el error ocurre a un nivel más bajo, como en el servidor web o en la configuración de PHP. En estos casos, tienes otras opciones:

Revisar los logs del servidor

Tu hosting guarda registros de todos los errores del servidor. Si tu hosting usa Syspanel, busca la sección "Registros" o "Logs". Ahí podrás ver errores de Apache, Nginx o PHP que no se muestran en pantalla.

Desactivar módulos uno por uno

Si el problema comenzó después de instalar un módulo nuevo, desactívalo. Para ello, renombra la carpeta del módulo en /modules/ (por ejemplo, de mimodulo a mimodulo_bak). Si la tienda vuelve a funcionar, ese es el culpable.

Revisar los permisos de archivos y carpetas

Los permisos incorrectos (como 777 en archivos que deberían ser 644) pueden causar errores extraños. Asegúrate de que las carpetas tengan permisos 755 y los archivos 644.

Cómo desactivar el modo debug correctamente

Una vez que hayas resuelto el problema, es crítico que desactives el modo debug. Dejarlo activo es un riesgo de seguridad grave.

Si lo activaste por el archivo defines.inc.php

Vuelve a abrir el archivo config/defines.inc.php y cambia true de nuevo a false:

define('_PS_MODE_DEV_', false);

Si lo activaste desde el panel de administración

Ve a "Parámetros Avanzados" > "Rendimiento" y selecciona la opción "Desactivado" en el modo de depuración. Guarda los cambios.

[TIP]
Después de desactivar el debug, borra la caché de PrestaShop (Parámetros Avanzados > Rendimiento > "Vaciar la caché") para asegurarte de que los cambios se aplican correctamente.

Preguntas frecuentes (FAQ)

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

No. Nunca dejes el modo debug activado en una tienda operativa. Expone información confidencial como rutas de archivos, consultas SQL y configuraciones del servidor, lo que facilita que un atacante encuentre vulnerabilidades. Úsalo solo para diagnosticar y desactívalo inmediatamente después.

¿El modo debug ralentiza mi tienda?

Sí, ligeramente. Al mostrar información adicional de errores y, si eliges la opción "con rendimiento", registrar consultas SQL, consume más recursos. Por eso, solo debe estar activo durante la resolución de problemas.

¿Puedo usar el modo debug para mejorar el rendimiento?

No directamente. El modo debug te muestra el rendimiento (tiempo de carga, número de consultas, etc.), lo que te ayuda a identificar cuellos de botella. Pero para optimizar, es mejor usar herramientas específicas de caché y análisis.

¿Qué hago si no puedo acceder al archivo defines.inc.php?

Si no puedes acceder por FTP o al administrador de archivos, contacta con tu proveedor de hosting. Ellos pueden hacer el cambio por ti o darte acceso. Si usas Syspanel, el acceso al administrador de archivos suele estar en el panel principal.

¿El modo debug funciona igual en todas las versiones de PrestaShop?

El método del archivo defines.inc.php funciona en todas las versiones. El método desde el panel de administración está disponible en PrestaShop 1.7 y 8.x. En versiones más antiguas (1.6), el panel es diferente, pero el archivo siempre es la opción segura.

Conclusión y buenas prácticas

Configurar debug prestashop es una habilidad esencial para cualquier persona que gestione una tienda online. Te convierte en un detective capaz de encontrar la causa raíz de cualquier problema, en lugar de quedarte bloqueado con una pantalla en blanco.

Recuerda las buenas prácticas:

• Activa el debug solo cuando lo necesites.
• Anota el error que ves y la ruta del archivo. Esa es tu pista principal.
• Desactívalo siempre al terminar.
• Si el error es complejo, busca en Google el mensaje exacto. Es muy probable que otro usuario haya tenido el mismo problema y haya compartido la solución.

Con esta guía, ya tienes las herramientas para afrontar los errores de tu PrestaShop con confianza. No temas a los errores; son solo mensajes que te dicen qué tienes que arreglar. ¡Manos a la obra y a resolver esos problemas!