WordPress Debug: Cómo Solucionar Errores Como un Profesional

¿Alguna vez has entrado a tu sitio web de WordPress y te has encontrado con una temida pantalla blanca? 😱 Es uno de los problemas más frustrantes porque no ofrece ninguna pista sobre qué salió mal. Afortunadamente, WordPress tiene una herramienta integrada muy poderosa para estos casos: el modo Debug.

Activar el modo debug es como pedirle a WordPress que te diga exactamente qué le duele. En lugar de una pantalla en blanco, te mostrará mensajes de error específicos que te guiarán directamente a la causa del problema. Esta guía te enseñará a usarlo paso a paso.

¿Qué es el Modo Debug de WordPress?

El modo Debug es una constante en la configuración de WordPress que, al ser activada, cambia el comportamiento de PHP (el lenguaje de programación en el que está escrito WordPress) para que muestre todos los errores, advertencias y avisos que normalmente permanecerían ocultos.

Es una herramienta de diagnóstico fundamental para desarrolladores y administradores de sitios. Te ayuda a identificar problemas con:

• Plugins: Conflictos entre plugins o código mal escrito.
• Temas (Themes): Errores en el archivo functions.php o en otras plantillas.
• Código personalizado: Errores de sintaxis al añadir un nuevo fragmento de código.
• Funciones obsoletas: Avisos sobre funciones de WordPress o PHP que ya no se recomiendan usar.

---

Cómo Activar el Modo Debug en WordPress

Para activar el modo debug, necesitarás editar el archivo wp-config.php, uno de los archivos más importantes de tu instalación.

⚠️ Advertencia: Antes de editar wp-config.php, siempre es una buena práctica hacer una copia de seguridad de este archivo. Un pequeño error al editarlo podría dejar tu sitio inaccesible.

Paso 1: Accede a los archivos de tu sitio

A través del Administrador de Archivos de tu cPanel (o panel de hosting): Es la forma más sencilla. Busca el Administrador de Archivos, navega a la carpeta raíz de tu instalación de WordPress (normalmente public_html) y allí encontrarás el archivo.

Paso 2: Edita el archivo wp-config.php

Una vez que hayas localizado el archivo, ábrelo para editarlo. Desplázate hacia abajo hasta que encuentres la siguiente línea de código:

define( 'WP_DEBUG', false );

Esta línea le dice a WordPress que mantenga el modo debug desactivado. Para activarlo, simplemente cambia false por true:

define( 'WP_DEBUG', true );

¡Y eso es todo! Guarda los cambios. Ahora, si visitas la página que te daba la pantalla blanca, en lugar del vacío verás mensajes de error que te indicarán qué está fallando.

---

Mejorando el Debug: Guardar Errores en un Archivo de Registro (Log)

Mostrar errores directamente en tu sitio web es útil para diagnosticar, pero es un gran riesgo de seguridad en un sitio en producción (un sitio en vivo que recibe visitantes). Los mensajes de error pueden revelar rutas de archivos y otra información sensible de tu servidor.

La práctica recomendada es hacer que WordPress guarde los errores en un archivo de registro privado. Para ello, añade las siguientes líneas de código justo debajo de define( 'WP_DEBUG', true );:

// Habilita el modo Debug
define( 'WP_DEBUG', true );

// Guarda los errores en un archivo debug.log dentro de la carpeta /wp-content/
define( 'WP_DEBUG_LOG', true );

// Oculta los errores en la pantalla del sitio
define( 'WP_DEBUG_DISPLAY', false );
@ini_set( 'display_errors', 0 );

Analicemos qué hace cada línea:

• WP_DEBUG_LOG: Cuando se establece en true, todos los errores se guardan en un archivo llamado debug.log dentro de la carpeta /wp-content/.
• WP_DEBUG_DISPLAY: Al ponerlo en false, te aseguras de que los errores no se muestren en las páginas de tu sitio, manteniendo la seguridad.

Con esta configuración, tu sitio seguirá funcionando (o mostrando la pantalla blanca), pero ahora tendrás un registro detallado de todo lo que ocurre «detrás de escena».

Cómo Leer e Interpretar el Archivo debug.log

Una vez activado WP_DEBUG_LOG, reproduce el error en tu sitio (por ejemplo, recarga la página que falla). Luego, ve a la carpeta /wp-content/ y busca el archivo debug.log.

Un mensaje de error típico se ve así:

[16-Oct-2025 11:00:15 UTC] PHP Fatal error:  Cannot redeclare my_custom_function() (previously declared in /home/user/public_html/wp-content/themes/my-theme/functions.php:25) in /home/user/public_html/wp-content/plugins/my-custom-plugin/my-custom-plugin.php on line 50

No te asustes por el código. Vamos a descomponerlo:

• PHP Fatal error: Este es el tipo de error. Un «Fatal error» es grave y detiene la ejecución del script (lo que a menudo causa la pantalla blanca). Otros tipos comunes son Warning (advertencia) y Notice (aviso), que son menos graves.
• Cannot redeclare my_custom_function(): Este es el mensaje del error. En este caso, nos dice que una función se está intentando definir dos veces.
• /home/user/public_html/wp-content/plugins/my-custom-plugin/my-custom-plugin.php: Esta es la pista más importante. Es la ruta exacta del archivo que está causando el problema. En este ejemplo, el culpable es un plugin llamado «my-custom-plugin».
• on line 50: Te dice el número de línea exacto dentro de ese archivo donde se encuentra el error.

Con esta información, ya sabes que el problema está en la línea 50 del archivo principal del plugin my-custom-plugin.

---

Solucionando Problemas Comunes con el Debug

Ahora que sabes cómo encontrar el error, aquí tienes cómo solucionar los más habituales:

Problema 1: Conflicto de Plugin

• Pista en debug.log: La ruta del archivo apunta a la carpeta /wp-content/plugins/nombre-del-plugin/.
• Solución: La forma más rápida de solucionarlo es desactivar ese plugin. Si no puedes acceder a tu panel de WordPress, usa tu Administrador de Archivos o FTP para ir a la carpeta /wp-content/plugins/ y renombra la carpeta del plugin problemático (por ejemplo, de nombre-del-plugin a nombre-del-plugin-desactivado). Esto lo desactivará de inmediato y tu sitio debería volver a funcionar.

Problema 2: Conflicto de Tema

• Pista en debug.log: La ruta del archivo apunta a /wp-content/themes/nombre-del-tema/, a menudo al archivo functions.php.
• Solución: Esto suele ocurrir después de añadir código personalizado o actualizar el tema. La solución es cambiar a un tema predeterminado de WordPress (como «Twenty Twenty-Three»). Si no tienes acceso al panel, renombra la carpeta de tu tema actual como hiciste con el plugin. WordPress automáticamente volverá a un tema por defecto.

Problema 3: Error de Sintaxis (Parse Error)

• Pista en debug.log: Verás un PHP Parse error, que generalmente significa que hay un error de tipeo en el código.
• Solución: Esto es muy común cuando se copia y pega código de tutoriales. El debug.log te dirá exactamente en qué archivo y línea está el error. Edita ese archivo, ve a la línea indicada y busca errores obvios como un punto y coma ; faltante, un paréntesis ( o una llave { sin cerrar.

No lo Olvides: Desactiva el Modo Debug

Una vez que hayas solucionado el problema, ¡es muy importante que desactives el modo debug!

Vuelve a tu archivo wp-config.php y cambia la línea de nuevo a false:

define( 'WP_DEBUG', false );

También es una buena idea eliminar el archivo debug.log de la carpeta /wp-content/ para no dejar registros de errores al alcance de otros.

¡Felicidades! Ahora tienes el conocimiento para diagnosticar y solucionar los problemas más comunes de WordPress por ti mismo. La pantalla blanca ya no es un misterio, sino un desafío que sabes cómo resolver.