Activar modo debug PrestaShop: muestra errores y soluciona problemas

¿Qué es el modo debug de PrestaShop y por qué es tu mejor aliado?

Cuando tu tienda online muestra una pantalla en blanco, un error 500 o un mensaje críptico, es normal sentir un poco de pánico. La buena noticia es que PrestaShop incluye una herramienta oculta y muy potente para desenmascarar estos problemas: el modo debug (también conocido como modo desarrollo o _PS_MODE_DEV_).

Activar el modo debug PrestaShop no es un paso obligatorio, pero se convierte en una necesidad cuando necesitas solucionar errores PrestaShop de forma rápida y precisa. En lugar de adivinar qué está fallando, este modo te muestra el error exacto, el archivo implicado y la línea de código donde se produce. Es como tener un mecánico que te dice exactamente qué pieza está rota y por qué, en lugar de decirte "el coche no arranca".

En esta guía, pensada para usuarios sin experiencia técnica, te explicaré paso a paso cómo activar este modo, qué información te va a mostrar y, lo más importante, cómo desactivarlo de forma segura cuando hayas terminado. No necesitas ser un programador para seguir esta guía, solo necesitas acceso a tu panel de control de hosting (como Syspanel) y un poco de paciencia.

[INFO] El modo debug no es una solución en sí misma, sino una herramienta de diagnóstico. Una vez que identifiques el error, podrás buscar una solución concreta o pedir ayuda a un desarrollador con la información exacta que necesitas.

Antes de empezar: prepara tu entorno de trabajo

Activar el modo debug es un proceso sencillo, pero requiere que tengas a mano dos herramientas fundamentales:

Acceso a tu panel de control de hosting (Syspanel): Aquí es donde gestionas los archivos de tu web. Recuerda que para acceder a Syspanel, debes usar el puerto 2106 (por ejemplo, https://tudominio.com:2106). Dentro de Syspanel, busca la sección de "Administrador de archivos" o "Gestor de archivos".
Un editor de texto plano: Puede ser el Bloc de notas de Windows, TextEdit en Mac (en modo texto plano) o el editor que incluya el propio Administrador de archivos de Syspanel. Evita usar procesadores de texto como Word, ya que añaden formato invisible que puede romper el código.

[WARNING] Antes de modificar cualquier archivo, siempre es recomendable hacer una copia de seguridad de tu tienda. Si algo sale mal, puedes restaurar la versión anterior sin perder datos.

Método 1: Activar el modo debug desde el archivo config/defines.inc.php (El método clásico)

Este es el método más común y funciona en la mayoría de las versiones de PrestaShop. Consiste en editar un archivo de configuración central.

Paso 1: Localiza el archivo correcto

Dentro del Administrador de archivos de Syspanel, navega hasta la carpeta raíz de tu instalación de PrestaShop. Normalmente se llama public_html o htdocs. Dentro de esa carpeta, busca la carpeta config. Dentro de config, encontrarás un archivo llamado defines.inc.php. Haz clic derecho sobre él y selecciona "Editar" o "Edit".

Paso 2: Busca la línea clave

Una vez que el archivo se abra en el editor, busca la siguiente línea de código (puedes usar la función de búsqueda del editor, normalmente Ctrl+F o Cmd+F):

define('_PS_MODE_DEV_', false);

Esta línea es la que controla el modo debug. El valor false significa que está desactivado.

Paso 3: Cambia el valor y guarda

Ahora, simplemente cambia false por true. La línea debería quedar así:

define('_PS_MODE_DEV_', true);

Guarda el archivo (con Ctrl+S o el botón de guardar) y cierra el editor.

Paso 4: Comprueba los errores

Ahora, recarga tu tienda en el navegador (usa Ctrl+F5 para forzar la recarga y evitar la caché). Si había un error, ya no verás una pantalla en blanco o un error 500, sino un mensaje detallado con:

El mensaje de error en sí (por ejemplo, "Fatal error: Uncaught Error...").
La ruta del archivo donde se produce el error.
El número de línea exacto.
Un "stack trace" (rastreo de llamadas) que muestra cómo se ha llegado a ese error.

Con esta información, puedes buscar en Google el mensaje de error o pedir ayuda en foros especializados. Es la forma más eficaz de solucionar errores PrestaShop.

[TIP] Anota el mensaje de error completo y el número de línea. Si necesitas contactar con soporte técnico, esta información es oro puro para ellos.

Método 2: Activar el modo debug desde el archivo .htaccess (Alternativa rápida)

Si el método anterior no funciona (por ejemplo, si el archivo defines.inc.php está protegido o no lo encuentras), existe una alternativa usando el archivo .htaccess, que también se encuentra en la raíz de tu instalación.

[WARNING] Este método puede no funcionar en todas las configuraciones de servidor y es menos fiable que el primero. Úsalo solo si el método 1 no te funciona.

Paso 1: Abre el archivo .htaccess

En la raíz de tu PrestaShop, busca el archivo .htaccess (ten en cuenta que empieza con un punto, por lo que puede estar oculto. En Syspanel, activa la opción de "Mostrar archivos ocultos" si es necesario). Edítalo con el editor de texto.

Paso 2: Añade las líneas de configuración

Al principio del archivo (después de la línea # ~~~start si existe, o justo al inicio), añade las siguientes líneas:

SetEnv PS_MODE_DEV "1"
SetEnv PS_MODE_DEV_DEBUG "1"

Paso 3: Guarda y prueba

Guarda el archivo y recarga tu tienda. Si el error se muestra de forma detallada, el método ha funcionado.

Método 3: Activar el modo debug desde el archivo settings.inc.php (Para versiones antiguas)

Si tienes una versión de PrestaShop anterior a la 1.6, es posible que no encuentres el archivo defines.inc.php. En su lugar, deberás buscar el archivo config/settings.inc.php.

Dentro de este archivo, busca una línea similar a esta:

define('_PS_MODE_DEV_', false);

Y cámbiala a true, igual que en el método 1. Guarda el archivo y listo.

¿Qué hago con tanta información? Cómo leer el error

Ahora que has activado el modo debug PrestaShop, verás una pantalla de error que puede parecer abrumadora. Vamos a desglosarla:

El mensaje de error: Es la primera línea y la más importante. Te dice qué tipo de error es (Error fatal, Aviso, Advertencia, etc.) y una descripción breve. Por ejemplo: Fatal error: Uncaught Error: Call to undefined method....
La ubicación del error: Te indica el archivo exacto y la línea donde se ha detectado el problema. Por ejemplo: en /home/tuusuario/public_html/modules/mimodulo/mimodulo.php en la línea 45.
El Stack Trace: Es una lista de todas las funciones que se estaban ejecutando en el momento del error. Es como el historial de llamadas. Te ayuda a entender cómo se ha llegado al error. A menudo, el problema real no está en la última línea del stack trace, sino en una de las primeras.

Con esta información, ya puedes actuar:

Si el error es de un módulo: Puedes desactivar ese módulo desde el administrador (si tienes acceso) o renombrar su carpeta en el servidor para desactivarlo manualmente.
Si el error es de tu tema: Prueba a cambiar temporalmente a un tema por defecto (como Classic) para ver si el problema persiste.
Si el error es del núcleo: Busca el mensaje en Google. Es muy probable que otro usuario haya tenido el mismo problema y haya compartido la solución.

Cómo desactivar el modo debug (¡Paso crucial!)

Una vez que hayas identificado y solucionado el error en PrestaShop, es imprescindible que desactives el modo debug. Dejarlo activado en una tienda en producción es un riesgo de seguridad grave, ya que expone información sensible de tu servidor (rutas, versiones de software, etc.) a cualquier visitante.

Para desactivarlo (Método 1 y 3):

Simplemente vuelve a editar el archivo que modificaste (defines.inc.php o settings.inc.php) y cambia el valor true de nuevo a false. Guarda el archivo.

Para desactivarlo (Método 2):

Elimina las dos líneas que añadiste al archivo .htaccess y guarda los cambios.

[WARNING] No olvides desactivar el modo debug. Es un error muy común dejarlo activado y puede comprometer la seguridad de tu tienda. Añade una nota mental o una alarma para hacerlo justo después de solucionar el problema.

Errores comunes y cómo el modo debug te ayuda a resolverlos

Aquí tienes algunos ejemplos de errores típicos que podrás diagnosticar gracias al modo debug:

Error 500 (Internal Server Error): Un clásico. Puede deberse a un archivo .htaccess corrupto, a un error de permisos en un archivo o carpeta, o a un conflicto entre módulos. El modo debug te dirá exactamente qué archivo está causando el problema.
Pantalla en blanco (White Screen of Death): Suele ser un error de PHP que no se muestra por estar el modo debug desactivado. Al activarlo, verás el error fatal y podrás actuar.
Errores de memoria (Allowed memory size exhausted): Este error indica que tu script necesita más memoria de la permitida. El modo debug te lo mostrará claramente. La solución suele ser aumentar el límite de memoria en el archivo php.ini o en el .htaccess.
Errores de conexión a la base de datos: El modo debug te mostrará si el problema es de credenciales incorrectas, de servidor caído, etc.

Preguntas frecuentes (FAQ) sobre el modo debug

¿Es peligroso activar el modo debug?
No es peligroso en sí mismo, pero sí es una puerta abierta a la información interna de tu servidor. Por eso, solo debe activarse temporalmente para diagnosticar y solucionar errores PrestaShop, y debe desactivarse inmediatamente después.

¿Puedo activar el modo debug si no tengo acceso al panel de administración de PrestaShop?
Sí. De hecho, es la vía principal. Puedes activarlo accediendo a los archivos de tu servidor a través de Syspanel (recuerda, puerto 2106), tal y como hemos explicado en esta guía.

¿El modo debug afecta al rendimiento de mi tienda?
Sí, puede hacer que la tienda sea ligeramente más lenta, ya que se registran más datos. Por eso, no es recomendable tenerlo activado en un entorno de producción.

¿Qué significa _PS_MODE_DEV_?
Es el nombre de la constante de PHP que controla el modo desarrollo o debug en PrestaShop. Cuando está en true, el sistema muestra los errores en pantalla.

¿Y si después de todo sigo sin poder solucionar el error?
No te preocupes. Con la información que te proporciona el modo debug, ya tienes el 90% del trabajo hecho. Ahora puedes buscar el error en Google, en foros de PrestaShop o contactar con tu proveedor de hosting o un desarrollador, dándoles el mensaje de error exacto.

Conclusión y buenas prácticas

Activar el modo debug PrestaShop es una habilidad esencial para cualquier propietario de una tienda online. Te permite pasar de la frustración de una pantalla en blanco a la claridad de un diagnóstico preciso. Es la herramienta definitiva para solucionar errores PrestaShop de forma autónoma.

Resumen de buenas prácticas:

Siempre haz una copia de seguridad antes de modificar archivos.
Activa el modo debug solo cuando lo necesites, y desactívalo en cuanto termines.
Guarda el mensaje de error para futuras consultas o para pedir ayuda.
Utiliza el acceso a Syspanel (puerto 2106) para gestionar tus archivos de forma segura.
Si no te sientes cómodo editando archivos, pide ayuda a un profesional. No tiene nada de malo, y es mejor prevenir que curar.

Con esta guía, ya tienes todo lo que necesitas para enfrentarte a los errores de tu PrestaShop con confianza. ¡Manos a la obra!