«Error al establecer una conexión con la base de datos» en WordPress: causas y solución

Respuesta corta: WordPress no consigue conectar con MySQL o MariaDB. Lo primero es comprobar que DB_NAME, DB_USER, DB_PASSWORD y DB_HOST en wp-config.php son correctos; si lo son, el servidor de base de datos está caído, saturado o sin disco. Si el mensaje cambia a «tablas no disponibles», hay que reparar la base de datos.

Qué significa «Error al establecer una conexión con la base de datos»

WordPress guarda todo el contenido (entradas, páginas, ajustes, usuarios, pedidos) en una base de datos MySQL o MariaDB. En cada visita, lo primero que hace es conectarse a ella con los datos de wp-config.php. Si esa conexión falla, no puede construir ninguna página y enseña:

• En español: «Error al establecer una conexión con la base de datos».
• En inglés: «Error establishing a database connection».

El mensaje es el mismo para causas muy distintas. Estas son las que nos encontramos:

1. Credenciales incorrectas: alguien cambió la contraseña del usuario de MySQL en el panel, o se migró la web y wp-config.php sigue con los datos del servidor viejo.
2. Servidor de base de datos caído: el proceso de MySQL se ha parado (por falta de memoria, por una actualización del sistema, por un reinicio que no lo arrancó).
3. Demasiadas conexiones: un pico de tráfico, un ataque de fuerza bruta o un plugin con consultas lentas agotan las conexiones permitidas.
4. Disco lleno: MySQL no puede escribir y deja de aceptar conexiones o se detiene.
5. Tablas dañadas: tras un corte o un disco lleno, alguna tabla queda marcada como corrupta.
6. DB_HOST mal puesto: en algunos hostings la base de datos no está en localhost, sino en otro servidor o en un socket concreto.

Cómo saber si te pasa

• El mensaje sale en todas las páginas, también en /wp-admin/. Si solo falla una parte de la web, probablemente sea otra cosa.
• Si en /wp-admin/ ves otro mensaje, del tipo «One or more database tables are unavailable. The database may need to be repaired», la conexión funciona pero hay tablas dañadas: ve directamente a la sección de reparación.
• Si es intermitente (a ratos sí, a ratos no), apunta a saturación: demasiadas conexiones o memoria insuficiente en el servidor.
• Si tienes varias webs en el mismo servidor y todas fallan a la vez, el problema es MySQL, no WordPress.

Paso 1: comprueba las credenciales de wp-config.php

La causa más común del error al establecer una conexión con la base de datos son unas credenciales mal puestas. Abre wp-config.php por FTP/SFTP, SSH o el gestor de archivos del panel y localiza estas líneas (en la documentación oficial de wp-config.php tienes el detalle de cada una):

define( 'DB_NAME', 'nombre_bd' );
define( 'DB_USER', 'usuario_bd' );
define( 'DB_PASSWORD', 'contraseña' );
define( 'DB_HOST', 'localhost' );

Compáralas con lo que dice el panel del hosting, en el apartado de bases de datos. Fíjate en los prefijos: muchos paneles añaden el nombre de la cuenta delante (cuenta_wp en lugar de wp).

La forma más rápida de salir de dudas es probar la conexión con esos mismos datos por SSH:

mysql -u usuario_bd -p -h localhost nombre_bd -e "SELECT 1;"

Si devuelve Access denied, el usuario o la contraseña no son correctos o el usuario no tiene permisos sobre esa base de datos. Si dice Can't connect to local MySQL server through socket o Connection refused, el servidor no está escuchando: ve al paso 2.

Con wp-cli también puedes comprobarlo, usando los datos de wp-config.php:

wp db check

Si no tienes SSH, puedes subir un fichero temporal de prueba a la raíz, abrirlo en el navegador y borrarlo justo después:

<?php
$c = mysqli_connect( 'localhost', 'usuario_bd', 'contraseña', 'nombre_bd' );
echo $c ? 'Conexión correcta' : 'Fallo: ' . mysqli_connect_error();

No lo dejes ahí ni un minuto más de lo necesario: contiene la contraseña de la base de datos.

Si las credenciales estaban mal, corrígelas en wp-config.php o restablece la contraseña del usuario en el panel y pon la nueva en el fichero.

Paso 2: comprueba que MySQL o MariaDB funciona

En un hosting compartido no puedes tocar el servidor: abre una incidencia con el proveedor indicando la hora exacta del fallo. En un VPS o servidor propio:

systemctl status mariadb    # o mysql, según la distribución
journalctl -u mariadb -n 50 --no-pager
df -h
free -m

Lo que suele aparecer:

• El servicio está parado y en el log hay un «Out of memory» o el kernel lo mató (oom-killer). Arráncalo con systemctl start mariadb y revisa el consumo de memoria del servidor; si no, volverá a pasar.
• El disco está al 100 %. Libera espacio (copias antiguas, logs, la papelera del hosting) y reinicia el servicio.
• Demasiadas conexiones («Too many connections» en el log). Compara las conexiones usadas con el máximo:

mysql -u root -p -e "SHOW VARIABLES LIKE 'max_connections'; SHOW GLOBAL STATUS LIKE 'Max_used_connections';"

Si llegas al máximo de forma habitual, sube max_connections con cabeza (cada conexión consume memoria) y busca la causa: bots atacando wp-login.php o xmlrpc.php, un plugin que lanza consultas pesadas o falta de caché de página.

Paso 3: comprueba DB_HOST

Si la web se ha migrado o el hosting ha cambiado de infraestructura, el valor de DB_HOST puede no ser localhost. Ejemplos válidos:

define( 'DB_HOST', 'localhost' );
define( 'DB_HOST', '127.0.0.1:3306' );
define( 'DB_HOST', 'localhost:/var/run/mysqld/mysqld.sock' );
define( 'DB_HOST', 'mysql.proveedor.com' );

El correcto lo da el panel del hosting. En algunos servidores localhost usa el socket y 127.0.0.1 usa TCP, y solo uno de los dos funciona.

Paso 4: repara las tablas dañadas

Si la conexión funciona pero WordPress habla de tablas no disponibles, haz antes una copia de la base de datos (wp db export copia.sql o desde phpMyAdmin) y después repara.

Con wp-cli:

wp db repair

Con la herramienta de WordPress: añade esta línea a wp-config.php, abre https://tuweb.com/wp-admin/maint/repair.php y pulsa «Reparar base de datos»:

define( 'WP_ALLOW_REPAIR', true );

Esa página no pide usuario ni contraseña, así que quita la línea en cuanto termines.

Por SSH, con acceso de administrador a MySQL:

mysqlcheck -u root -p --auto-repair --check nombre_bd

Errores habituales

• Cambiar la contraseña de MySQL en el panel y olvidarse de wp-config.php. Es la causa más común y la más rápida de arreglar.
• Restaurar la base de datos sin mirar el disco. Si el disco sigue lleno, el error vuelve en horas.
• Subir max_connections a lo loco. Si el servidor no tiene memoria para tantas conexiones, cambias un error por otro: MySQL se cae por falta de RAM.
• Dejar WP_ALLOW_REPAIR activado o el fichero de prueba de conexión en la raíz.
• Ignorar los cortes cortos. Si la web falla dos minutos cada noche, algo (una copia, un cron) está saturando el servidor a esa hora.

Para agencias: enterarte antes que el cliente

Este error tiene una trampa: WordPress lo sirve con un código 500, pero si hay una página db-error.php personalizada que devuelve 200, o una caché o CDN que enseña la última copia buena de la portada, un monitor que solo mire el código puede darlo por bueno mientras el resto de páginas fallan.

Jeffrey lo vigila de dos formas. Su sonda de disponibilidad comprueba la portada cada uno o dos minutos y, si recibe un error 5xx o no hay respuesta en tres muestras seguidas, abre un aviso urgente de caída. Y la prueba diaria con navegador real, en móvil y escritorio, lee el texto de la página: si aparece «Error al establecer una conexión con la base de datos» o «Error establishing a database connection», lo marca como «No conecta con la base de datos», repite la prueba a los cinco minutos y, si se confirma, te avisa como error crítico con la URL afectada.

Si es urgente y no sabes por dónde empezar, escríbenos y lo miramos.

Tienes el resto de errores en la guía de errores de WordPress que tumban tu web, y si lo que ves es un código de servidor, en la de error 500 y 503 en WordPress.

Preguntas frecuentes