Cómo habilitar el modo Debug en WordPress: guía completa

El modo Debug de WordPress es un sistema de diagnóstico integrado en el núcleo del CMS que registra errores PHP, avisos y advertencias generados por el código de WordPress, los plugins y el tema activo. Activarlo te permite identificar la causa exacta de errores, pantallas en blanco o comportamientos inesperados que de otro modo serían invisibles.

La configuración del modo Debug se realiza editando el archivo wp-config.php, ubicado en la carpeta raíz de tu instalación de WordPress. Puedes acceder a él desde el Administrador de Archivos de cPanel o mediante FTP con FileZilla.

⚠️ No dejes el modo Debug activo en un sitio en producción con tráfico real. Las constantes WP_DEBUG y WP_DEBUG_DISPLAY en true pueden mostrar información técnica sensible (rutas del servidor, nombres de usuario, etc.) a los visitantes del sitio. Úsalas solo para diagnóstico y desactívalas cuando termines.

Constantes de debug disponibles en WordPress

Constante	Valor	Efecto
WP_DEBUG	true	Activa el modo debug. Habilita el registro de errores, avisos y notices de PHP.
WP_DEBUG	false	Desactiva el modo debug (valor por defecto).
WP_DEBUG_DISPLAY	false	Oculta los errores en la pantalla (no los muestra a los visitantes). Recomendado en producción.
WP_DEBUG_LOG	true	Guarda los errores en un archivo debug.log dentro de wp-content/.
WP_DEBUG_LOG	'/ruta/al/archivo.log'	Guarda los errores en un archivo con ruta y nombre personalizados.
SCRIPT_DEBUG	true	Fuerza a WordPress a cargar las versiones no minificadas de los archivos CSS y JS del núcleo.
SAVEQUERIES	true	Guarda las consultas a la base de datos para su análisis. Impacto en rendimiento — solo para desarrollo.

Configuración recomendada según el contexto

Para producción — Debug activo pero silencioso

Esta configuración activa el debug y guarda los errores en un archivo de log, pero no los muestra en pantalla a los visitantes:

// Activar modo Debug
define('WP_DEBUG', true);

// No mostrar errores en pantalla
define('WP_DEBUG_DISPLAY', false);
@ini_set('display_errors', 0);

// Guardar errores en wp-content/debug.log
define('WP_DEBUG_LOG', true);

Con esta configuración, los errores se escriben en wp-content/debug.log y puedes revisarlos cuando necesites sin exponer información al público.

Para desarrollo local — Debug completo con salida en pantalla

Esta configuración muestra los errores directamente en pantalla, útil cuando trabajas en local o en un entorno de desarrollo sin visitantes:

// Activar modo Debug con salida en pantalla
define('WP_DEBUG', true);
define('WP_DEBUG_DISPLAY', true);
define('WP_DEBUG_LOG', true);

Para desactivar el debug completamente

define('WP_DEBUG', false);

Cómo editar wp-config.php paso a paso

1. Accede al Administrador de Archivos de cPanel o conecta por FTP con FileZilla.
2. Navega hasta la carpeta raíz de tu instalación de WordPress (normalmente public_html o el subdirectorio donde instalaste WordPress).
3. Localiza el archivo wp-config.php y ábrelo para editar.
4. Busca la línea que contiene define('WP_DEBUG'. Si ya existe, modifica el valor. Si no existe, añade las constantes antes de la línea /* That's all, stop editing! */.
5. Guarda los cambios.

ℹ️ Las constantes de debug deben colocarse antes de la línea /* That's all, stop editing! Happy publishing. */ para que WordPress las procese correctamente.

Cómo leer el archivo de log de debug

Cuando WP_DEBUG_LOG está en true, WordPress guarda los errores en el archivo wp-content/debug.log. Para revisarlo:

• Desde el Administrador de Archivos: navega a wp-content/ y abre el archivo debug.log con el editor de texto.
• Desde SSH: ejecuta tail -f /ruta/a/wp-content/debug.log para ver los errores en tiempo real mientras reproduces el problema.
• Desde FTP: descarga el archivo debug.log a tu equipo y ábrelo con cualquier editor de texto.

Una vez reproducido el error que estás investigando, busca en el log las líneas más recientes — estarán al final del archivo. Cada línea suele indicar el tipo de error (PHP Notice, PHP Warning, PHP Fatal error), el mensaje descriptivo, el archivo afectado y la línea exacta del código.

Ejemplo de entrada en el log:

[23-Sep-2025 18:42:11 UTC] PHP Warning: Undefined variable $ejemplo in /home/usuario/public_html/wp-content/plugins/mi-plugin/mi-plugin.php on line 45

⚠️ El archivo debug.log puede crecer mucho si hay errores recurrentes. Vacíalo o elimínalo periódicamente, y desactiva WP_DEBUG cuando termines el diagnóstico.

Situaciones frecuentes con el modo Debug

Activo WP_DEBUG pero no veo ningún error en pantalla

Verifica que WP_DEBUG_DISPLAY no está en false en tu wp-config.php. También puede estar sobreescrito por una configuración en el servidor (php.ini o .htaccess) que deshabilita la salida de errores. En ese caso, usa WP_DEBUG_LOG para guardar los errores en el archivo de log y revisarlos desde ahí.

El archivo debug.log no se crea aunque WP_DEBUG_LOG está en true

El directorio wp-content/ puede no tener permisos de escritura. Verifica los permisos de la carpeta wp-content/ — deben ser 755 o 775. También puede ocurrir que WP_DEBUG esté en false — WP_DEBUG_LOG solo funciona cuando WP_DEBUG está en true.

La web muestra pantalla en blanco después de activar el debug

La pantalla blanca suele indicar un error fatal de PHP que impide que WordPress cargue. Con WP_DEBUG_DISPLAY en true debería mostrarse el mensaje de error. Si sigue en blanco, revisa directamente el archivo wp-content/debug.log o el log de errores de PHP de cPanel en Estadísticas → Registro de errores.

Aparecen muchos PHP Notice o PHP Deprecated en el log

Los notices y los deprecated son avisos de código que debería actualizarse, pero no son errores fatales — el sitio funciona con normalidad. Si tienes muchos, es señal de que algún plugin o tema está desactualizado o usa funciones antiguas de PHP. Lo recomendable es actualizarlos. Si el volumen de notices dificulta encontrar el error real que buscas, puedes usar error_reporting(E_ALL & ~E_NOTICE & ~E_DEPRECATED) temporalmente para filtrarlos.

Preguntas frecuentes sobre el modo Debug de WordPress

¿Cómo activar el modo Debug en WordPress?

Edita el archivo wp-config.php en la raíz de tu WordPress y añade (o modifica) la línea: define('WP_DEBUG', true); antes de /* That's all, stop editing! */. Para guardar los errores en un log sin mostrarlos en pantalla añade también: define('WP_DEBUG_DISPLAY', false); y define('WP_DEBUG_LOG', true);

¿Dónde se guarda el archivo de log de debug de WordPress?

Por defecto en wp-content/debug.log. Si quieres cambiar la ruta, puedes pasar una ruta personalizada como valor de la constante: define('WP_DEBUG_LOG', '/ruta/personalizada/mi-log.log');

¿Es seguro tener WP_DEBUG activado en producción?

Solo si WP_DEBUG_DISPLAY está en false — así los errores no se muestran a los visitantes. La combinación recomendada para producción es WP_DEBUG true + WP_DEBUG_DISPLAY false + WP_DEBUG_LOG true, que registra los errores de forma silenciosa sin exponerlos al público.

¿El modo Debug afecta al rendimiento de WordPress?

Mínimamente cuando solo está activo WP_DEBUG y WP_DEBUG_LOG. El impacto es mayor si activas SAVEQUERIES (guarda todas las consultas SQL) o si el sitio genera muchos errores y el log crece continuamente. Para uso normal de diagnóstico el impacto es insignificante.

¿Cómo desactivar el modo Debug después de diagnosticar el problema?

Edita wp-config.php y cambia define('WP_DEBUG', true); a define('WP_DEBUG', false);. Guarda el archivo. Si también tenías WP_DEBUG_LOG activo, recuerda vaciar o eliminar el archivo wp-content/debug.log para que no siga acumulando tamaño.