Cómo usar el modo debug de PrestaShop para solucionar errores
Cuando tu tienda PrestaShop muestra una pantalla en blanco, un error 500 o un mensaje críptico que no te dice nada, la primera reacción suele ser el pánico. Pero respira, porque existe una herramienta pensada exactamente para esto: el modo debug de PrestaShop.
Activar este modo es como abrir el capó del coche para ver qué pieza falla. En lugar de esconder el problema, PrestaShop te mostrará el error real, la línea de código y el archivo implicado. Con esa información, podrás solucionarlo tú mismo o darle a tu equipo técnico los datos exactos para que lo arreglen en minutos.
En esta guía extensa y práctica, te voy a explicar qué es el modo debug, cómo activarlo paso a paso (incluso si no tienes acceso al panel de administración) y cómo interpretar los errores para que dejes de sufrir con los famosos "errores PrestaShop".
¿Qué es exactamente el modo debug de PrestaShop?
El modo debug (o modo depuración) es una funcionalidad interna de PrestaShop que cambia la forma en que la plataforma gestiona los errores.
En condiciones normales, PrestaShop oculta los detalles técnicos de un fallo por seguridad. Solo muestra un mensaje genérico como "Error interno del servidor" o una página en blanco. Esto es útil para los clientes, pero inútil para ti como administrador.
Cuando activas el modo debug, la cosa cambia por completo. La tienda pasa a mostrar:
- El mensaje de error específico (por ejemplo: "Duplicate entry...")
- El archivo donde ocurre el fallo (por ejemplo:
/classes/db/Db.php) - La línea exacta del código que lo provoca (por ejemplo:
Línea 345) - Un stack trace completo, es decir, la secuencia de llamadas que llevaron al error.
Con estos datos, cualquier desarrollador (o tú mismo con un poco de búsqueda en Google) puede identificar la causa raíz del problema. Sin el modo debug, estarías a ciegas.
¿Cuándo deberías activar el modo debug?
No es necesario tenerlo activo siempre. De hecho, no lo recomiendo en una tienda en producción, porque expone información sensible (rutas del servidor, versiones de PHP, etc.) a cualquier visitante.
Actívalo solo en estas situaciones:
- La tienda muestra una pantalla blanca o un error 500.
- No puedes acceder al panel de administración.
- Necesitas depurar PrestaShop tras instalar un módulo o plantilla nueva.
- Recibes un error al hacer una acción concreta (añadir producto, procesar pago, etc.).
- Quieres comprobar si un problema viene de un override o de un hook.
[WARNING]: Si activas el modo debug en una tienda en línea con tráfico real, hazlo durante unos minutos y desactívalo en cuanto hayas recopilado la información. Exponer rutas internas puede facilitar ataques externos.**
Método 1: Activar el modo debug desde el panel de administración (la vía fácil)
PrestaShop incluye una opción nativa para activar el modo debug sin tocar archivos. Es la forma más rápida y segura para usuarios novatos.
Sigue estos pasos:
- Accede a tu panel de administración de PrestaShop (normalmente en
tudominio.com/admin1234). - Ve al menú Parámetros avanzados (o "Advanced Parameters").
- Dentro, haz clic en Rendimiento (o "Performance").
- Busca la sección Modo de depuración (Debug mode).
- Verás dos opciones:
- Nunca (modo normal, recomendado para producción).
- Sí (activa el modo debug).
- Selecciona Sí y pulsa Guardar.
En ese mismo momento, si recargas la tienda, verás los errores detallados en pantalla.
[TIP]: Si no encuentras la opción, es posible que tu versión de PrestaShop sea antigua (1.6 o anterior). En ese caso, usa el método 2 que te explico a continuación.**
Método 2: Activar el modo debug editando el archivo define.inc.php (a prueba de todo)
Si no tienes acceso al panel de administración (porque la tienda está rota), o si la opción no aparece, tendrás que hacerlo a mano. No te preocupes, es muy sencillo y solo necesitas un editor de texto y acceso FTP o al administrador de archivos de tu hosting.
Paso 1: Localiza el archivo define.inc.php
El archivo se encuentra en la raíz de tu instalación de PrestaShop, dentro de la carpeta /config. La ruta completa suele ser:
/public_html/config/define.inc.php
Si usas un hosting compartido, la ruta puede variar ligeramente. Si no lo encuentras, usa el buscador de archivos de tu panel de control (cPanel, Syspanel, etc.).
Paso 2: Edita el archivo con un editor de texto
Descarga el archivo a tu ordenador con un cliente FTP (como FileZilla) o ábrelo directamente desde el administrador de archivos del hosting (por ejemplo, en Syspanel, el panel de control que incluye el puerto 2106 para la gestión de archivos).
Ábrelo con un editor de texto plano (nada de Word). El Bloc de notas de Windows o Sublime Text son perfectos.
Paso 3: Busca la línea de configuración del modo debug
Dentro del archivo, busca una línea que contenga _PS_MODE_DEV_. Normalmente está en la parte superior del archivo y se ve así:
define('_PS_MODE_DEV_', false);
El valor false significa que el modo debug está desactivado.
Paso 4: Cambia el valor a true
Cámbialo a:
define('_PS_MODE_DEV_', true);
Guarda el archivo y súbelo de nuevo al servidor (reemplazando el original). Si lo editaste directamente desde el hosting, solo guarda los cambios.
Paso 5: Comprueba el resultado
Recarga tu tienda. Ahora deberías ver el mensaje de error detallado en lugar de la pantalla en blanco.
[WARNING]: Haz siempre una copia de seguridad del archivo define.inc.php antes de modificarlo. Si algo sale mal, podrás restaurarlo fácilmente.**
Método 3: Activar el modo debug desde el archivo .htaccess (para errores de servidor)
A veces, el error no viene de PrestaShop sino del propio servidor (por ejemplo, un error 500 por un límite de memoria). En ese caso, activar el modo debug de PrestaShop no mostrará nada útil.
Para depurar errores de PHP a nivel de servidor, puedes añadir temporalmente estas líneas al archivo .htaccess que está en la raíz de tu tienda:
php_flag display_errors on
php_value error_reporting E_ALL
Esto fuerza a PHP a mostrar todos los errores, avisos y warnings directamente en el navegador.
[INFO]: Si tu hosting usa PHP-FPM o una configuración que no permite php_flag, puedes crear un archivo php.ini en la raíz con estas líneas: display_errors = On y error_reporting = E_ALL.**
Cómo interpretar los errores que verás con el modo debug
Una vez activado, verás una pantalla con mucha información técnica. Te enseño a leerla para que no te abrumes.
El mensaje de error principal
Es la primera línea, suele empezar por algo como:
[Error] Duplicate entry '1' for key 'PRIMARY'
O:
[Warning] Trying to access array offset on value of type null
Este mensaje te dice qué ha fallado. Si es un error de base de datos, suele indicar una tabla o una consulta. Si es un error de PHP, te dice la operación ilegal.
El archivo y la línea
Justo debajo aparece:
File: /home/public_html/modules/mimodulo/mimodulo.php
Line: 432
Esto te indica dónde está el problema. En este ejemplo, el error está en un módulo llamado "mimodulo", en la línea 432. Con esto, sabes que el problema no es del núcleo de PrestaShop, sino de un módulo de terceros.
El stack trace
Es una lista numerada que muestra la secuencia de llamadas antes de que ocurriera el error. Es muy útil para ver qué función llamó a qué otra.
Por ejemplo:
0. /classes/module/Module.php:123
1. /classes/Hook.php:456
2. /classes/Dispatcher.php:789
Esto te indica que el error ocurrió en un hook llamado desde el dispatcher. Si ves un módulo repetido, es casi seguro que el culpable es ese módulo.
Errores comunes que puedes resolver con el modo debug
1. Error de memoria: "Allowed memory size exhausted"
Este es uno de los errores PrestaShop más frecuentes. El mensaje suele ser:
Fatal error: Allowed memory size of 134217728 bytes exhausted
Solución: Aumenta el límite de memoria de PHP. Puedes hacerlo desde el archivo define.inc.php añadiendo:
ini_set('memory_limit', '256M');
O desde el .htaccess:
php_value memory_limit 256M
2. Error de base de datos: "Table doesn't exist"
Table 'prestashop.ps_product_shop' doesn't exist
Solución: Esto suele pasar tras una restauración incompleta o una migración. Necesitas verificar que todas las tablas de PrestaShop existen en tu base de datos. Si falta alguna, puedes restaurarla desde la copia de seguridad.
3. Error de módulo: "Class not found"
Class 'MyClass' not found
Solución: El módulo intenta cargar una clase que no existe. Suele ser por una instalación incompleta del módulo o por un conflicto con otro módulo. Desactiva el módulo desde el panel de administración (si puedes acceder) o elimina su carpeta temporalmente.
Cómo desactivar el modo debug (y por qué deberías hacerlo)
Una vez hayas solucionado el problema, desactiva el modo debug. No es buena idea dejarlo activo en una tienda en producción por seguridad y rendimiento.
Para desactivarlo desde el panel:
Repite el proceso del Método 1 y selecciona Nunca en la opción de modo debug.
Para desactivarlo manualmente:
Edita el archivo define.inc.php y cambia:
define('_PS_MODE_DEV_', true);
De vuelta a:
define('_PS_MODE_DEV_', false);
Y si añadiste líneas al .htaccess, elimínalas.
Preguntas frecuentes (FAQ) sobre el modo debug de PrestaShop
¿El modo debug afecta al rendimiento de mi tienda?
Sí, ligeramente. Al mostrar información de depuración, PrestaShop consume un poco más de recursos. Por eso se recomienda activarlo solo cuando lo necesites.
¿Es seguro tener el modo debug activado?
No del todo. Expone rutas internas del servidor, versiones de PHP y de PrestaShop. Esta información puede ser usada por atacantes para encontrar vulnerabilidades. Actívalo solo temporalmente.
¿Puedo activar el modo debug sin acceso FTP?
Sí, si tienes acceso al panel de administración de PrestaShop, puedes activarlo desde los parámetros avanzados. Si no tienes acceso al panel, necesitarás FTP o un administrador de archivos en tu hosting.
¿Qué hago si el modo debug no muestra ningún error?
Si activas el modo debug y la pantalla sigue en blanco, el problema puede estar en el servidor (PHP no se ejecuta correctamente). Prueba a revisar los logs del servidor en Syspanel (recuerda que el acceso es por el puerto 2106) o contacta con tu proveedor de hosting.
¿El modo debug funciona en PrestaShop 8?
Sí, el modo debug sigue presente en las últimas versiones de PrestaShop, aunque la interfaz puede variar ligeramente. El archivo define.inc.php sigue siendo la vía de activación manual más fiable.
Conclusión y mejores prácticas
El modo debug de PrestaShop es tu mejor aliado cuando aparecen errores crípticos. Te permite depurar PrestaShop de forma efectiva, identificando el archivo y la línea exacta del problema.
Para terminar, te dejo un resumen de buenas prácticas:
- Activa el modo debug solo cuando lo necesites y desactívalo al terminar.
- Guarda siempre una copia de los archivos que modifiques.
- Interpreta el error antes de buscar soluciones: un error en un módulo no se soluciona tocando el núcleo.
- Si el error es complejo y no te sientes seguro, busca ayuda profesional. Tener el mensaje de error exacto de antemano te ahorrará tiempo y dinero en soporte técnico.
Con esta guía, ya no volverás a sentirte perdido ante una pantalla blanca. Ahora sabes exactamente cómo abrir el capó y ver qué está pasando bajo el capó de tu tienda.
[TIP]: Si tu hosting utiliza Syspanel (el panel de control con acceso por el puerto 2106), puedes acceder fácilmente al administrador de archivos y al editor de archivos para modificar define.inc.php sin necesidad de descargar nada.**
