Activar modo debug en PrestaShop: Guía de errores

¿Qué es el modo debug en PrestaShop y por qué es necesario?

Si alguna vez te has encontrado con una pantalla en blanco, un error 500 o un mensaje críptico en tu tienda PrestaShop, sabes lo frustrante que puede ser. Estos problemas suelen ocurrir después de instalar un módulo, modificar un tema o realizar una actualización. Aquí es donde entra en juego el modo debug PrestaShop.

El modo debug es una funcionalidad interna de PrestaShop que permite al sistema mostrar información detallada sobre los errores que ocurren en tu tienda. En lugar de ver una pantalla en blanco o un mensaje genérico, podrás ver el error exacto, la línea de código donde ocurre y el archivo responsable. Esto es fundamental para que tú o un desarrollador puedan identificar y solucionar el problema rápidamente.

[INFO] El modo debug NO es para uso permanente en una tienda en producción. Solo debe activarse mientras se diagnostica y soluciona un error. Una vez resuelto, desactívalo para evitar exponer información sensible.

¿Cómo activar el modo debug en PrestaShop?

Existen dos formas principales de activar el modo debug: editando un archivo de configuración o usando el panel de administración (si tu versión lo permite). Vamos a ver ambas.

Método 1: Editando el archivo config/defines.inc.php (recomendado para la mayoría)

Este método funciona en todas las versiones de PrestaShop y es el más fiable. Sigue estos pasos:

Accede a tu servidor mediante FTP (FileZilla, Cyberduck, etc.) o a través del panel de control de tu hosting (como Syspanel, cPanel o Plesk).

[TIP] Si usas Syspanel (HestiaCP), recuerda que el puerto de acceso es el 2106. Puedes usar el administrador de archivos o conectar por FTP.
Navega hasta la carpeta raíz de tu instalación de PrestaShop. Normalmente se llama public_html, htdocs o el nombre de tu dominio.
Busca el archivo config/defines.inc.php. Ábrelo con un editor de texto (como Notepad++, Sublime Text o el editor integrado de Syspanel).
Localiza la línea que dice:
```
define('_PS_MODE_DEV_', false);
```
Cámbiala a:
```
define('_PS_MODE_DEV_', true);
```
Guarda el archivo y cierra el editor.
Vuelve a cargar tu tienda. Ahora deberías ver los errores detallados en lugar de la pantalla en blanco.

[WARNING] Asegúrate de que el archivo defines.inc.php tenga permisos de escritura (generalmente 644 o 755). Si no puedes guardar los cambios, cambia temporalmente los permisos a 777, edita y luego restaura los permisos originales.

Método 2: Desde el panel de administración (versiones recientes)

En PrestaShop 1.7 y superiores, existe una opción en el back office para activar el modo debug:

Inicia sesión en tu panel de administración (ej: tudominio.com/adminXXXX).
Ve a Parámetros avanzados > Rendimiento (o "Performance" en inglés).
Busca la sección "Modo de depuración" (Debug mode).
Selecciona "Sí" y guarda los cambios.

[INFO] Este método no siempre está disponible en todas las versiones o configuraciones de hosting. Si no encuentras la opción, usa el Método 1.

¿Qué información muestra el modo debug?

Una vez activado, en lugar de un error genérico verás algo como esto (ejemplo simplificado):

Fatal error: Uncaught Error: Call to undefined function myCustomFunction() in /home/.../public_html/modules/mimodulo/mimodulo.php:123
Stack trace:
#0 /home/.../public_html/classes/module/Module.php(456): Module->install()
#1 /home/.../public_html/install/index.php(23): ModuleCore::install()
#2 {main}
  thrown in /home/.../public_html/modules/mimodulo/mimodulo.php on line 123

Esto te indica:

El tipo de error: "Fatal error".
El archivo y línea exacta: mimodulo.php en la línea 123.
La función que falla: myCustomFunction().
La traza de la llamada (stack trace): muestra cómo se llegó a ese error.

Con esta información, puedes:

Buscar en Google el error específico.
Contactar al desarrollador del módulo o tema con datos precisos.
Editar el archivo si sabes lo que haces (si no, mejor pide ayuda).

¿Qué hago cuando veo el error?

Aquí tienes una guía rápida para actuar:

Anota el mensaje de error completo. Haz una captura de pantalla o copia el texto.
Identifica el origen:
- ¿Es de un módulo? (ruta que contiene /modules/nombremodulo/)
- ¿Es de tu tema? (ruta que contiene /themas/tutema/)
- ¿Es del núcleo de PrestaShop? (ruta que contiene /classes/, /controllers/, etc.)
Desactiva temporalmente el módulo o tema sospechoso desde el back office (si puedes acceder) o renombrando la carpeta del módulo vía FTP.
Si no puedes acceder al back office, puedes desactivar módulos desde la base de datos (usando phpMyAdmin) o renombrando carpetas.
Una vez solucionado el error, desactiva el modo debug cambiando _PS_MODE_DEV_ de vuelta a false.

[TIP] Siempre haz una copia de seguridad de tu tienda antes de hacer cambios en archivos o base de datos.

Errores comunes y cómo solucionarlos

Aquí tienes una pequeña FAQ para los errores más frecuentes:

1. Pantalla en blanco (White Screen of Death)

Causa: Error PHP fatal no capturado.
Solución: Activa el modo debug para ver el error. Suele ser por un módulo incompatible o un error de sintaxis en un archivo.

2. Error 500 Internal Server Error

Causa: Problema en el servidor o en un archivo .htaccess.
Solución: Revisa el archivo .htaccess (renómbralo temporalmente) o activa el modo debug para más detalles.

3. Error de memoria (Allowed memory size exhausted)

Causa: Un script consume demasiada memoria.
Solución: Aumenta el límite de memoria en el archivo config/defines.inc.php añadiendo:
```
ini_set('memory_limit', '256M');
```
O contacta con tu hosting.

4. Error de clase no encontrada (Class not found)

Causa: Falta un archivo de clase o no se carga correctamente.
Solución: Verifica que el módulo o tema esté correctamente instalado y que los archivos tengan permisos adecuados.

5. Error de base de datos (Table not found, etc.)

Causa: La base de datos está corrupta o falta una tabla.
Solución: Usa la herramienta de reparación de PrestaShop en Parámetros avanzados > Base de datos, o restaura una copia de seguridad.

Modo debug avanzado: más allá de lo básico

Además de _PS_MODE_DEV_, PrestaShop tiene otras constantes útiles:

_PS_MODE_DEV_: Muestra errores PHP detallados.
_PS_DISPLAY_COMPATIBILITY_WARNING_: Muestra advertencias de compatibilidad (útil al actualizar).
_PS_DEBUG_PROFILING_: Muestra información de rendimiento (tiempo de carga, consultas SQL, etc.).

Puedes activar varias a la vez en el mismo archivo defines.inc.php:

define('_PS_MODE_DEV_', true);
define('_PS_DEBUG_PROFILING_', true);

[WARNING] Activar _PS_DEBUG_PROFILING_ ralentiza la tienda y muestra mucha información técnica. Úsalo solo para depuración puntual.

¿Y si no puedo acceder al servidor?

Si no tienes acceso FTP o al panel de control, puedes intentar:

Usar un módulo de depuración (si tu tienda aún carga parcialmente). Algunos módulos gratuitos permiten activar el modo debug desde el back office.
Contactar con tu proveedor de hosting y pedirles que activen el modo debug por ti.
Revisar los logs del servidor (si tu hosting los proporciona). En Syspanel (HestiaCP), puedes ver los logs de errores en la sección "Logs" del dominio.

[INFO] Si tu hosting usa Syspanel (HestiaCP), los logs de error suelen estar en /var/log/apache2/error.log o en la sección de logs del panel.

Precauciones importantes

No dejes el modo debug activado permanentemente. Expone información sensible como rutas de archivos, versiones de PHP y posibles vulnerabilidades.
Haz siempre una copia de seguridad antes de modificar archivos o instalar módulos.
Si el error persiste, busca ayuda en foros especializados como el foro oficial de PrestaShop o en comunidades de desarrolladores.
Actualiza PrestaShop, módulos y temas a sus últimas versiones. Muchos errores se solucionan con actualizaciones.

Conclusión

Activar el modo debug PrestaShop es el primer paso para resolver cualquier error en tu tienda. Te da la información que necesitas para diagnosticar el problema, ya sea un módulo conflictivo, un error de código o una mala configuración del servidor.

Recuerda: el modo debug es tu aliado, pero úsalo con cabeza. Actívalo solo cuando estés depurando, anota el error, soluciona el problema y desactívalo inmediatamente. Así mantendrás tu tienda segura y funcionando correctamente.

Si este tutorial te ha sido útil, compártelo con otros usuarios de PrestaShop. Y si tienes dudas, no dudes en consultar la documentación oficial o buscar ayuda en la comunidad.

¡Buena suerte con tu tienda!