Activar el registro de depuración de WordPress (modo debug de WordPress)

Cuando abres tu sitio WordPress y ves una página en blanco o un error 500, WordPress está suprimiendo un mensaje de error que identificaría la causa de inmediato. Activar el registro de depuración de WordPress le indica a WordPress que escriba cada error, advertencia y aviso PHP en un archivo — wp-content/debug.log — para que puedas ver exactamente qué plugin, tema o línea de código es responsable.

TL;DR: Añade estas tres constantes a wp-config.php, justo encima de la línea /* That's all, stop editing! Happy publishing. */ — define( 'WP_DEBUG', true );, define( 'WP_DEBUG_LOG', true ); y define( 'WP_DEBUG_DISPLAY', false );. Tras guardar, recarga la página y WordPress escribirá todos los errores PHP en wp-content/debug.log. Una vez que hayas terminado de solucionar el problema, desactiva el modo debug de WordPress antes de publicar en producción.

Modo debug de WordPress según el entorno de Hosting

La forma de acceder a wp-config.php — y dónde acaba debug.log — depende de tu entorno de Hosting. Usa la sección que corresponda a tu configuración.

Hosting compartido (cPanel / FTP)

En servidores de Hosting compartido como Bluehost, SiteGround o Hostinger, wp-config.php se encuentra en el directorio raíz de WordPress, normalmente public_html/. Edítalo usando el Gestor de archivos de cPanel o un cliente FTP como FileZilla.

Problema habitual de permisos: si WordPress no puede escribir debug.log, el directorio wp-content/ necesita ser escribible por el servidor web. El permiso estándar es 755 para directorios. No lo establezcas en 777 en un Hosting compartido — eso hace que el directorio sea escribible por cualquiera y supone un riesgo de seguridad.

Según los tickets de soporte de WP STAGING, el Hosting compartido es donde debug.log más a menudo falla silenciosamente, porque muchos servidores de Hosting compartido capturan los errores PHP en su propio registro del lado del servidor en lugar de permitir que WordPress cree debug.log. Si el archivo nunca aparece tras activar WP_DEBUG, pregunta a tu proveedor de Hosting dónde almacenan su registro de errores PHP.

VPS / Servidor gestionado (SSH)

Con acceso SSH, edita wp-config.php directamente desde la línea de comandos:

nano /var/www/html/wp-config.php

Tras guardar, sigue el registro en tiempo real para ver los errores a medida que ocurren:

tail -f /var/www/html/wp-content/debug.log

Si no se crea debug.log, comprueba que el directorio wp-content/ sea propiedad del usuario del servidor web (www-data en Ubuntu/Debian, apache o nginx en CentOS/AlmaLinux):

ls -la /var/www/html/wp-content/
chown www-data:www-data /var/www/html/wp-content/

Desarrollo local (LocalWP / DevKinsta / XAMPP)

debug.log aparece en la misma ubicación wp-content/debug.log, pero la ruta base depende de tu entorno local:

• LocalWP: ~/Local Sites/<site-name>/app/public/wp-content/debug.log
• DevKinsta: ~/DevKinsta/projects/<site-name>/app/public/wp-content/debug.log
• XAMPP en Windows: C:xampphtdocs<site-name>wp-contentdebug.log

Los entornos locales raramente tienen problemas de permisos porque el servidor web y tu cuenta de usuario se ejecutan como el mismo proceso. Si debug.log nunca aparece, confirma que tu wp-config.php esté en la raíz de WordPress y no en un directorio padre.

Sitio de staging de WP STAGING

En nuestras pruebas con WP STAGING, activar el modo debug en el clon de staging es el enfoque más seguro — el clon es una copia exacta del sitio en producción, por lo que cualquier error que reproduzcas coincidirá con el entorno en producción sin afectar a los visitantes reales.

Para activar el modo debug en tu sitio de staging, edita el wp-config.php dentro del directorio del sitio de staging. WP STAGING crea el sitio de staging como un subdirectorio o subdominio separado con su propio wp-config.php, por lo que los cambios allí no afectan a la configuración de WP_DEBUG del sitio en producción.

Si no puedes iniciar sesión en tu sitio de staging, el registro de depuración es el primer lugar donde buscar — los fallos de inicio de sesión en staging son la mayoría de las veces errores fatales de PHP que solo aparecen en el registro.

Cómo activar el modo debug de WordPress

Puedes activar el «modo debug» de WordPress editando unas pocas líneas en el archivo wp-config.php de tu instalación de WordPress:

1. Inicia sesión en cPanel o accede a tu sitio por FTP
2. Usa el gestor de archivos de cPanel o tu cliente FTP y edita el archivo wp-config.php
3. Copia las líneas siguientes en el archivo wp-config.php o, si ya existen, cambia sus valores a true:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );

Atención: asegúrate de copiar las líneas exactamente como se muestran y no olvides ningún punto y coma u otro carácter.

1. Pega las líneas copiadas justo encima de la línea que dice
   /* That's all, stop editing! Happy publishing. */

Tras recargar el sitio web, WordPress escribirá todos los errores PHP en el archivo debug.log.
WordPress guarda ese archivo en la carpeta: wp-content/debug.log

Mostrar errores en el frontend de WordPress

Si quieres ver los errores del registro de depuración directamente en pantalla en lugar de activar el archivo debug.log, cambia la línea que dice define( 'WP_DEBUG_DISPLAY', false );

Renómbrala a: define( 'WP_DEBUG_DISPLAY', true );.

WordPress no crea el archivo de registro debug.log

Algunos proveedores de Hosting[1] no permiten la creación del archivo debug.log de WordPress. Interceptan todos los errores PHP y hacen que WordPress los escriba en un archivo de registro separado.

Si WordPress no puede crear debug.log, sigue este árbol de decisión para encontrar la causa:

1. Busca un archivo de registro alternativo. Comprueba en la raíz del sitio si existe un archivo llamado error_log o busca una carpeta /logs/. Muchos servidores de Hosting compartido, como HostGator, redirigen los errores PHP a su propio registro del lado del servidor en lugar de permitir que WordPress escriba debug.log. Si no encuentras ningún archivo de registro, pregunta a tu proveedor de Hosting dónde almacenan los registros de errores PHP.

2. Comprueba los permisos del directorio. wp-content/ debe ser escribible por el servidor web. En un servidor con acceso SSH, ejecuta:

ls -la /path/to/wp-content/

El directorio debe ser propiedad de www-data (Ubuntu/Debian) o apache (CentOS). El permiso estándar es 755. Si el directorio es propiedad de root y el usuario del servidor web no puede escribir en él, debug.log fallará silenciosamente.

3. Comprueba si display_errors está anulando tu configuración. Algunas configuraciones de php.ini del servidor o directivas de .htaccess establecen php_flag display_errors Off, lo que puede suprimir la salida incluso cuando WP_DEBUG_DISPLAY es true. Comprueba la configuración PHP del panel de control de tu Hosting o pregunta a tu proveedor.

4. Comprueba si algún plugin must-use está suprimiendo errores. Los archivos en wp-content/mu-plugins/ se cargan antes que todo lo demás y pueden anular los manejadores de errores de WordPress. Si tu proveedor de Hosting instaló un plugin must-use que intercepta errores, puede impedir que se escriba debug.log. Inspecciona cualquier archivo en wp-content/mu-plugins/ si ese directorio existe.

5. Comprueba el nivel de error_reporting. Si error_reporting está configurado demasiado restrictivamente — por ejemplo, solo a E_ERROR — PHP no registrará advertencias y avisos. WordPress establece error_reporting(E_ALL) cuando WP_DEBUG es true, pero un plugin o la configuración del servidor puede cambiar esto después de que WordPress se cargue. Consulta la documentación de error_reporting de PHP para ver la lista completa de constantes y lo que cubre cada nivel.

6. Comprueba que el directorio de la ruta del registro exista. Si ya has establecido WP_DEBUG_LOG en una ruta personalizada, confirma que el directorio en esa ruta existe y es escribible por el servidor web.

Como alternativa, puedes usar el método mencionado anteriormente y cambiar
define( 'WP_DEBUG_DISPLAY', false ); a
define( 'WP_DEBUG_DISPLAY', true );

Si funciona, verás los errores relevantes en el frontend. Eso te ayudará a resolver el error fatal.

Encontrarás instrucciones más detalladas sobre cómo activar el modo debug de WordPress en la documentación de depuración de WordPress.

En el momento de redactar este artículo: [1] HostGator

Método alternativo para depurar errores fatales cuando no se genera debug.log

A veces, al activar el modo WP_DEBUG para solucionar un error fatal, puede ocurrir que tu proveedor de Hosting impida la creación del archivo debug.log. Incluso establecer WP_DEBUG_DISPLAY en true no siempre ayuda a mostrar el error en el frontend.

Si te encuentras en esta situación, aquí tienes una solución práctica que funciona cuando nada más lo hace.

Forzar la visualización de errores en wp-config.php

Este fragmento de código fuerza la visualización del error fatal:

register_shutdown_function(function () {
    $error = error_get_last();
    if ($error) {
        print_r($error);
    }
});

🚨 Recuerda eliminar el fragmento después de depurar y úsalo solo cuando tengas acceso FTP para una restauración segura.

Leer el registro de depuración de WordPress

Una vez que existe debug.log, ábrelo en cualquier editor de texto. Cada línea sigue este patrón:

[DD-Mon-YYYY HH:MM:SS UTC] PHP Fatal error: <message> in /path/to/file.php on line N
[DD-Mon-YYYY HH:MM:SS UTC] PHP Warning: <message> in /path/to/file.php on line N
[DD-Mon-YYYY HH:MM:SS UTC] PHP Notice: <message> in /path/to/file.php on line N

Esto es lo que significa cada clase de error y cuándo actuar:

PHP Fatal error — PHP detuvo la ejecución. Esta es siempre la causa de una página en blanco o un error 500. La ruta del archivo y el número de línea en la entrada del registro te muestran exactamente dónde mirar. Encuentra el plugin o tema cuyo archivo se nombra en la entrada y desactívalo para confirmarlo.

PHP Warning — PHP encontró algo inesperado pero siguió ejecutándose. Las advertencias no causan páginas en blanco por sí solas, pero a menudo indican un error que se convertirá en un error fatal en condiciones diferentes. Si estás activando el registro de depuración de WordPress para identificar advertencias PHP relacionadas con límites de configuración PHP, una advertencia de max_input_vars de un plugin con muchos formularios es una entrada habitual.

PHP Notice — PHP anotó un posible problema como una variable indefinida. Los avisos raramente indican un error real en producción, pero si el mismo aviso aparece miles de veces por carga de página puede señalar un problema de bucle o recursión que degrada el rendimiento.

Errores de base de datos $wpdb — Las líneas que empiezan con WordPress database error indican que una consulta falló. Normalmente apuntan a un plugin que genera una consulta SQL malformada o a un problema en las tablas de la base de datos de WordPress que la consulta tiene como objetivo. El mensaje de error incluye la consulta que falló, lo que facilita identificar el plugin causante.

Cuando encuentres un error fatal o una advertencia repetida, mira la ruta del archivo en la entrada del registro. Si pertenece a un plugin o tema, desactívalo, recarga la página y confirma que las entradas del registro se detienen.

Si el registro de depuración muestra errores de REST API en WordPress, la entrada del registro normalmente nombra la función exacta que falló — sigue la guía dedicada desde ese punto de partida. Si muestra errores ERR_CONNECTION_REFUSED, estos se originan en la capa del servidor o de red, no en PHP. Para errores 414 Request-URI Too Large, el registro normalmente identifica qué plugin está generando la URL demasiado larga.

Cambiar la ubicación del archivo debug.log

Puedes cambiar la ruta que WordPress usa para el registro de errores cambiando el valor de la constante WP_DEBUG_LOG.

Abre wp-config.php y busca la línea que contiene WP_DEBUG_LOG.

Busca: define( 'WP_DEBUG_LOG', true );

Cámbiala a: define( 'WP_DEBUG_LOG', '/logs/errors.log' );

Esto permite a WordPress escribir los mensajes de error en una ruta de archivo diferente.

Como ruta de destino también puedes usar /dev/stderr o /dev/stdout. Esto es útil en Docker u otros entornos en contenedores donde quieres todos los registros en un flujo de salida compartido.

Desactivar el modo debug de WordPress tras la resolución de problemas

Una vez que hayas terminado de investigar, desactiva el modo debug de inmediato. El archivo debug.log es accesible desde la web por defecto en wp-content/debug.log, y puede contener detalles de errores de base de datos, rutas de archivos y otra información del servidor que no debería ser legible públicamente.

Elimina el archivo debug.log y desactiva el registro de errores cambiando define( 'WP_DEBUG', true ); de vuelta a define( 'WP_DEBUG', false );.

Siempre desactiva el modo debug de WordPress antes de publicar en producción cuando trabajes en un sitio de staging. El flujo de trabajo de publicación de WP STAGING es el punto de control adecuado para confirmar que WP_DEBUG está desactivado antes de que el clon sobrescriba el sitio en producción.

Artículos relacionados

• Página en blanco en un sitio de staging de WordPress
• Cómo solucionar el error 500 y la página en blanco de WordPress
• Cómo depurar errores JavaScript en la consola del navegador