Entender los errores de WordPress y depurar tu web

Pantalla en blanco, «Ha habido un error crítico en esta web.», error 500 o imposible conectar con la base de datos: detrás de cada mensaje de WordPress hay una causa concreta, casi siempre anotada en algún registro. Esta guía explica cómo interpretar los errores habituales, usar el modo de recuperación, activar la depuración sin exponer la web y qué herramientas permiten encontrar al culpable en pocos minutos.

El primer paso: encontrar el mensaje real

El mensaje que ve el visitante es deliberadamente vago: no debe revelar las rutas del servidor. El error real está, de más fácil a más difícil de consultar:

1. en el correo del modo de recuperación, enviado a la dirección de administración cuando se produce un error fatal;
2. en los registros de errores de PHP del hosting (área de cliente, cPanel, Plesk);
3. en el registro de depuración de WordPress, una vez activado;
4. en la consola del navegador para los errores de JavaScript (editor de bloques bloqueado, un botón que ya no responde).

Antes de buscar, pregúntate qué ha cambiado: la actualización de un plugin, una nueva versión de PHP en el hosting, una modificación del tema. Nueve de cada diez veces, la causa está ahí.

Los errores de WordPress más frecuentes

Lo que ves	Causa probable	Primera acción
Página en blanco	Error fatal de PHP con la visualización de errores desactivada	Leer el registro de errores, desactivar el último plugin modificado
«Ha habido un error crítico en esta web.»	Error fatal en un plugin o en el tema	Seguir el enlace del correo de recuperación
Error 500	.htaccess no válido, límite del servidor, error de PHP	Renombrar .htaccess, leer el registro del servidor
404 en todas las páginas salvo la portada	Reglas de reescritura perdidas	Ajustes, Enlaces permanentes, Guardar cambios
«Error al establecer una conexión con la base de datos»	Credenciales incorrectas en wp-config.php, servidor MySQL caído	Comprobar las credenciales, contactar con el hosting
«Allowed memory size… exhausted»	Memoria PHP insuficiente o un plugin que consume demasiado	Aumentar WP_MEMORY_LIMIT, buscar la fuga
«No disponible temporalmente por mantenimiento programado. Vuelve a comprobarlo en unos minutos.»	Actualización interrumpida, archivo .maintenance olvidado	Borrar .maintenance, volver a lanzar la actualización
Demasiadas redirecciones	Dirección del sitio en HTTP detrás de un proxy en HTTPS	Comprobar siteurl, home y la detección de HTTPS

Memoria agotada

Por defecto, WordPress pide 40 MB de memoria (64 MB en multisitio) para la parte pública y hasta 256 MB en la administración, sin poder superar el límite fijado por el hosting. Puedes subir el primero en wp-config.php con define( 'WP_MEMORY_LIMIT', '256M' );. Si el error vuelve con más memoria, hay un plugin en bucle: seguir aumentando solo retrasa la caída.

Modo mantenimiento bloqueado

Durante una actualización, WordPress crea un archivo .maintenance en la raíz. Lo ignora por sí solo al cabo de diez minutos; si el mensaje persiste, borra el archivo y vacía la caché de páginas, que puede haber guardado la pantalla de mantenimiento. Después, vuelve a lanzar la actualización interrumpida, porque el plugin afectado puede haber quedado incompleto.

El modo de recuperación tras un error crítico

Desde WordPress 5.2, un error fatal activa el modo de recuperación: WordPress envía a la dirección de administración un correo que nombra el plugin o el tema responsable e incluye un enlace de acceso especial. Ese enlace abre la administración con el componente defectuoso en pausa solo para ti, el tiempo necesario para desactivarlo o actualizarlo. El enlace solo es válido durante un tiempo limitado.

¿No llega el correo? Puede que la dirección de administración esté desactualizada o que la web no envíe correos. Puedes definir otra dirección con la constante RECOVERY_MODE_EMAIL, o desactivar el plugin sin pasar por la administración:

# Sin cargar los plugins ni el tema que provocan el error
wp plugin list --status=active --skip-plugins --skip-themes
wp plugin deactivate nombre-del-plugin --skip-plugins --skip-themes

# Sin WP-CLI: renombrar la carpeta del plugin por SFTP
# wp-content/plugins/nombre-del-plugin  pasa a  nombre-del-plugin.off

Activar la depuración sin exponer la web

El modo de depuración se configura en wp-config.php, antes de la línea «That's all, stop editing! Happy publishing.» (¡Eso es todo, deja de editar!). En una web en producción hay que registrar los errores sin mostrarlos nunca, y escribir el registro fuera de la carpeta pública:

define( 'WP_DEBUG', true );
// Registro fuera de la carpeta pública (adapta la ruta a tu hosting)
define( 'WP_DEBUG_LOG', '/home/cuenta/logs/wp-errors.log' );
// Nunca mostrar errores a los visitantes
define( 'WP_DEBUG_DISPLAY', false );
@ini_set( 'display_errors', 0 );
// Solo para un error de JavaScript del núcleo: scripts sin minificar
// define( 'SCRIPT_DEBUG', true );

Con WP_DEBUG_LOG en true, el registro se escribe en wp-content/debug.log, una dirección que todo el mundo conoce y que los bots prueban sin parar. Este archivo contiene rutas del servidor, nombres de plugins y a veces consultas SQL o direcciones de correo: nunca lo dejes accesible públicamente en producción. Mejor una ruta fuera de la carpeta pública, bloquea el acceso al archivo desde el servidor y, una vez encontrado el problema, vuelve a poner WP_DEBUG en false y borra el registro. Nuestro artículo sobre los archivos sensibles expuestos muestra cómo comprobarlo, y nuestra guía de wp-config.php detalla los demás ajustes.

El método para aislar al culpable

Para aislar sin romper la web de los visitantes, el plugin Health Check & Troubleshooting ofrece un «Modo de diagnóstico» que desactiva los plugins y cambia de tema solo para tu sesión. En un entorno de pruebas, puedes desactivarlo todo directamente y reactivar los elementos uno a uno.

Las herramientas de diagnóstico

• Salud del sitio (Herramientas): la pestaña Estado señala los problemas conocidos (PHP antiguo, tareas programadas con retraso, peticiones externas bloqueadas); la pestaña Información muestra la configuración completa, lista para copiar y enviar a soporte.
• Query Monitor: plugin gratuito que muestra, solo a los administradores, los errores PHP de la página, las consultas SQL lentas o duplicadas, las llamadas HTTP y el componente responsable de cada una. Desactívalo cuando termines el diagnóstico.
• WP-CLI: wp doctor no viene incluido por defecto, pero wp core verify-checksums, wp plugin list y --skip-plugins bastan en la mayoría de los casos.
• Consola del navegador (F12): errores de JavaScript y peticiones fallidas (403, 500) cuando el editor o un formulario deja de responder.

How Do I Debug WordPress? Enable Logs, Find Errors, Recover Your SiteAl hacer clic, el vídeo se carga desde youtube-nocookie.com (YouTube, Google). No se carga nada antes de tu clic.

Los errores relacionados con la versión de PHP

WordPress 7 exige como mínimo PHP 7.4 y recomienda PHP 8.3 o superior. El paso a una nueva versión de PHP es la causa más frecuente de errores críticos «sin haber tocado nada»: el hosting cambia la versión y un plugin antiguo usa una función eliminada. El aviso «Deprecated» de hoy es el error fatal de la próxima versión.

• Antes de cambiar de versión, haz pruebas en un entorno de pruebas con el registro de depuración activado y lee los avisos.
• Si la web se cae tras el cambio, vuelve a la versión anterior en el panel del hosting mientras actualizas o sustituyes el plugin responsable.
• No te quedes en una versión sin soporte por un solo plugin: sustitúyelo. El calendario está en nuestro artículo sobre las versiones de PHP sin soporte.

Saber qué cambió antes de la caída

La pregunta «¿qué ha cambiado?» es más fácil de responder con un historial. WP Masquerade Pro mantiene un registro de actividad de los administradores (plugins activados, desactivados o actualizados, ajustes modificados, con el autor y la hora), detecta con el control de integridad cualquier archivo del núcleo modificado y te envía alertas por correo. No es una herramienta de depuración: no lee los errores de PHP. Pero a menudo responde a la primera pregunta del diagnóstico. La versión gratuita, por su parte, elimina los rastros de WordPress del código de las páginas, lo que no sustituye a la protección del archivo debug.log.

Preguntas frecuentes

¿Cómo soluciono «Ha habido un error crítico en esta web.»?

Abre el correo de recuperación enviado a la dirección de administración, sigue el enlace y desactiva o actualiza el componente indicado. Si no hay correo, desactiva el plugin con WP-CLI usando --skip-plugins o renombrando su carpeta por SFTP, y después lee el registro de errores.

¿Dónde está el archivo debug.log?

Por defecto en wp-content/debug.log cuando WP_DEBUG_LOG vale true. Es mejor indicar una ruta fuera de la carpeta pública y borrar el archivo cuando termine el diagnóstico.

¿Se puede dejar WP_DEBUG activado en producción?

Solo con la visualización desactivada y un registro fuera de la carpeta pública, durante el diagnóstico. En condiciones normales, déjalo en false: el registro crece y un archivo olvidado se convierte en una fuga de información.

¿Por qué mi web muestra un error 500 sin ningún mensaje?

El error suele venir del servidor, antes incluso de que cargue WordPress: una regla no válida en .htaccess, un límite de recursos, la versión de PHP. Renombra .htaccess, lee el registro de errores del servidor en el panel del hosting y contacta con su soporte si el registro está vacío.

Fuentes

• WordPress Developer: depuración en WordPress (enlace externo, se abre en una pestaña nueva)
• Make WordPress Core: el modo de recuperación de errores fatales en 5.2 (enlace externo, se abre en una pestaña nueva)
• WordPress.org: requisitos (enlace externo, se abre en una pestaña nueva)
• WordPress.org: Query Monitor (enlace externo, se abre en una pestaña nueva)