How to Fix "Error Establishing a Database Connection" in WordPress

"Error Establishing a Database Connection" is one of the most alarming messages WordPress can display. The entire site goes white except for that single line of text. No admin access. No frontend. Just a blank screen and a cryptic message.

The good news: this error has a fairly small set of root causes, and most of them can be fixed in under 10 minutes if you follow the right sequence. This guide walks through every cause from most to least common.

What this error actually means

WordPress cannot connect to your MySQL or MariaDB database. That can happen because:

1. The credentials in wp-config.php are wrong
2. The database server is down or overloaded
3. The database itself is corrupted
4. You have hit the maximum connection limit on the server
5. A recent migration left the wrong DB_HOST value

The error appears on both the frontend (/) and the admin (/wp-admin/). If only the admin throws the error, scroll to the "Corrupted tables" section.

Step 1 - Check wp-config.php credentials

Open wp-config.php in the root of your WordPress install. Look for these four constants:

define( 'DB_NAME',     'your_database_name' );
define( 'DB_USER',     'your_database_user' );
define( 'DB_PASSWORD', 'your_database_password' );
define( 'DB_HOST',     'localhost' );

DB_NAME - The exact name of the database. Log in to cPanel / phpMyAdmin / your hosting panel and verify it exists under your account. A common mistake after migrations is having a staging database name still set.

DB_USER - The MySQL user assigned to this database. The user must have full privileges on DB_NAME. Check this in cPanel > MySQL Databases > Current Users.

DB_PASSWORD - Copy-paste it rather than typing. Passwords with special characters (@, #, $) sometimes need escaping. If the password contains a single quote, wrap the value in double quotes: define( 'DB_PASSWORD', "pa$$word#1" );

DB_HOST - Usually localhost. On some managed hosts (Kinsta, Cloudways, WP Engine) this is a different value:

• Kinsta: uses localhost
• Cloudways: uses the internal server IP, e.g. 10.0.0.1
• Some shared hosts: 127.0.0.1 or a specific hostname like mysql.host.com

Check your hosting panel's MySQL section for the correct host. Using 127.0.0.1 instead of localhost sometimes resolves connection issues because it forces a TCP connection instead of a Unix socket.

After updating wp-config.php, reload the site. If it works, you are done.

Step 2 - Test the connection manually

If credentials look correct but the error persists, test the connection manually. Create a temporary file test-db.php in your WordPress root:

<?php
$conn = new mysqli( 'localhost', 'db_user', 'db_pass', 'db_name' );
if ( $conn->connect_error ) {
    die( 'Connection failed: ' . $conn->connect_error );
}
echo 'Connected successfully';
$conn->close();

Visit https://yoursite.com/test-db.php. It will either confirm the connection works or give a more specific MySQL error message.

Delete this file immediately after testing - it exposes your database credentials.

Step 3 - Check if MySQL is running

If you manage your own server (VPS or dedicated), the database server may have crashed. SSH in and check:

# For systemd (Ubuntu 20.04+, CentOS 7+)
sudo systemctl status mysql
sudo systemctl status mariadb

# Restart if stopped
sudo systemctl restart mysql

Check MySQL's error log for why it crashed:

sudo tail -100 /var/log/mysql/error.log

Common reasons for MySQL crashes:

• Out of disk space (df -h to check)
• Out of memory (MySQL killed by the OOM killer - check dmesg | grep -i "killed process")
• Corrupted InnoDB tablespace

If MySQL keeps crashing, the underlying cause is usually disk space or RAM. Managed hosts (Kinsta, Cloudways) handle this for you and alert before it becomes critical.

Step 4 - Check max connections

MySQL has a maximum connection limit. On shared hosting this can be as low as 25. On VPS it defaults to 151. When a spike in traffic hits, connections queue up and new ones get refused.

Check current connections:

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

If Threads_connected is near max_connections, you have hit the ceiling. Temporary fix:

SET GLOBAL max_connections = 300;

Permanent fix: add max_connections = 300 to /etc/mysql/mysql.conf.d/mysqld.cnf under [mysqld] and restart MySQL.

The better long-term fix is to enable a connection pooler like ProxySQL, or to identify and kill long-running queries that are holding connections open:

SHOW PROCESSLIST;
KILL <process_id>;

Step 5 - Repair corrupted database tables

If the frontend works but /wp-admin/ shows the database error, or if MySQL is running fine but WordPress still fails, your tables may be corrupted. This often happens after a server crash mid-write.

WordPress has a built-in repair tool. Add this to wp-config.php:

define( 'WP_ALLOW_REPAIR', true );

Then visit: https://yoursite.com/wp-admin/maint/repair.php

This page is accessible without being logged in while WP_ALLOW_REPAIR is set, so remove the constant immediately after running the repair.

Alternatively, repair via MySQL CLI:

mysqlcheck -u db_user -p --repair --all-databases

Or target just the WordPress database:

mysqlcheck -u db_user -p --repair your_database_name

Step 6 - Check recent changes

Think about what changed just before the error appeared:

• Did you migrate the site? The DB_HOST, DB_USER, and DB_NAME from the old server will not match the new one.
• Did you change your database password in cPanel but forget to update wp-config.php? This is the single most common cause on shared hosting.
• Did a maintenance plugin or backup plugin crash mid-operation? Some backup plugins export and re-import tables, which can leave them in an inconsistent state.
• Did your hosting plan renew or expire? Some hosts suspend databases before suspending the website.

Step 7 - Contact your host

At this point, if none of the above resolves the issue, the problem is on the server side. Your host can check:

• MySQL error logs you may not have access to
• Whether the database server is under load from another customer on the same machine
• Whether your database was suspended due to abuse or billing issues

Managed WordPress hosts like Kinsta and WP Engine have 24/7 support that responds in under 3 minutes and can diagnose server-side database issues directly.

Preventing this error in the future

Use a managed host

The majority of "database connection" support tickets I handle come from clients on cheap shared hosting. The MySQL servers on shared hosts are oversubscribed. Moving to a managed host (Kinsta, Cloudways) almost eliminates this class of error.

Monitor your database size

Large databases (over 1 GB) are more prone to corruption and slow queries that exhaust connections. Tools like WP Umbrella alert you before size becomes critical.

Set up uptime monitoring

A service like UptimeRobot (free tier available) will alert you the moment your site goes down, so you can fix it before your client notices. Configure it to check both the frontend and a page that requires a database query.

Regular database optimisation

Run this via WP-CLI monthly to reclaim overhead from deleted posts, revisions, and transients:

wp db optimize
wp transient delete --all

Quick reference: most common causes

Related reading

• WordPress Database Optimization Guide
• Fix WordPress PHP Memory Exhausted Error
• Fix WordPress White Screen of Death