Error establishing a database connection: what to check, in order

Error establishing a database connection. That is the whole message. WordPress is not being unhelpful on purpose: at the point this fires it has no database, so it has no theme, no plugins and nothing to say beyond the fact that the conversation failed.

What WordPress is actually reporting

Every page load starts with WordPress connecting to MySQL using four values from wp-config.php: database name, user, password and host. If that connection fails for any reason, you get this page. Four quite different problems collapse into one sentence:

• The credentials are wrong or the user lost its grants.
• The database server is unreachable, or refusing new connections.
• The database server is up but the specific database is gone.
• Tables are corrupted badly enough that the connection dies on first query.

Resist the urge to start editing wp-config.php. Three of those four have nothing to do with it, and a typo in that file turns a recoverable problem into a longer one.

Credentials or connectivity: tell them apart first

This single test splits the four into two pairs, and it takes about a minute. Create a file called dbtest.php in your site root, with your real values from wp-config.php:

<?php
$link = @mysqli_connect('DB_HOST', 'DB_USER', 'DB_PASSWORD', 'DB_NAME');
echo $link ? 'Connected fine.' : 'Failed: ' . mysqli_connect_error();

Load yoursite.com/dbtest.php, read the result, and delete the file straight away - it contains your database password in plain text. The error it prints is the one WordPress is hiding:

• Access denied for user is credentials. Go to the next section.
• Can't connect to MySQL server or Connection refused is the server. Skip ahead.
• Unknown database means the database itself is missing, usually after a failed migration or a host-side restore.
• Too many connections is capacity, which is its own thing and very common on shared hosting.

If it is the credentials

Something changed them, because credentials do not rot on their own. The usual causes, in order of likelihood:

• You migrated the site, and the new host uses different values.
• Someone rotated the database password in the hosting panel.
• A security plugin or a host-side cleanup reset the user.
• The site was restored from a backup taken on a different server.

Get the current values from your hosting panel rather than from memory, and check one detail people miss: the host. localhost and 127.0.0.1 are not interchangeable. The first uses a Unix socket, the second uses TCP, and plenty of hosts accept only one. Some managed hosts need a full hostname like mysql.yourhost.com or a non-standard port appended as host:3307. Copy what the panel says, exactly.

If the user and password are right and access is still denied, the user has lost its grants on that database. That is a hosting-panel fix, not a WordPress one: re-add the user to the database with full privileges.

If the database server is the problem

Too many connections is the one you are most likely to hit, and it is usually traffic rather than breakage. Shared hosting caps concurrent connections per account, and a traffic spike, a crawler, or one badly written plugin running an unindexed query on every page load will exhaust it. The site recovers on its own and then fails again at the next busy moment, which makes it maddening to reproduce.

The honest fixes are caching so most visitors never touch MySQL at all, finding the slow query, or more capacity. Restarting does nothing except reset the clock.

Connection refused means MySQL is not running. On a VPS, systemctl status mysql and the MySQL error log will tell you why: out of disk is the classic, and InnoDB will refuse to start rather than risk corruption. On shared or managed hosting you cannot see any of this, so check the host's status page and open a ticket. It is very often not your site at all.

If it is neither

Connection succeeds, WordPress still shows the error, and wp-admin may offer to repair the database. That points at corrupted tables, usually after an unclean shutdown or a disk filling up mid-write. Add this to wp-config.php:

define('WP_ALLOW_REPAIR', true);

Then visit yoursite.com/wp-admin/maint/repair.php and run the repair. It works without logging in, by design, because the login itself needs the database.

Afterwards

Once the site is back, work out which of the four it was and write it down. "It fixed itself" almost always means connection exhaustion, which will return, and the fix for that is caching or a query, never a restart.

The part worth changing is not the fix, it is the delay. This error produces no email, no alert and no log entry anyone reads. The site is simply down until a human happens to look, and on a store that is the single most expensive silence in the whole stack. The downtime calculator on the WooCommerce page puts a number on it with your own order volume, which is usually more persuasive than any argument.

For the other WordPress white screen, the one that says there has been a critical error and really is your PHP, the steps are on the WordPress page.