How to fix "Error establishing a database connection"

Your site has been replaced by a white page carrying a single sentence: Error establishing a database connection. No menu, no styling, no admin area. It is one of the more alarming things WordPress does, and one of the more fixable.

The message means exactly what it says, and no more. WordPress keeps every post, page, setting and user in a MySQL database, and it just tried to open that database and could not. It is not telling you the data is gone. It is telling you the door did not open.

The five causes, in the order worth checking

Work down this list. It is ordered by how often each turns out to be the culprit, not by how difficult it is to check, so start at the top even if the top looks too simple.

1. The credentials in wp-config.php no longer match

This is the most common cause by a wide margin, and it is nearly always the explanation when the error appears immediately after a migration, a restore, or a password reset.

Open wp-config.php in the root of your site. Near the top you will find four lines:

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

Every one of these has to match what actually exists on the server. Open the database section of your hosting control panel and compare:

• DB_NAME — does a database with exactly that name exist? Many hosts prefix database names with your account name, and the prefix is easy to lose when copying a site between servers.
• DB_USER — does that user exist, and is it assigned to that database? A user that exists but has not been granted access to the database produces this error just as reliably as a user that does not exist at all.
• DB_PASSWORD — you cannot read this back from the panel. If there is any doubt, set a new password on the database user and paste the same value into wp-config.php.
• DB_HOST — localhost is correct on most shared hosting. If your host uses a separate database server, it will be a hostname they have given you.

2. The database user has lost its privileges

A user can exist, have the right password, and still be refused — because it is no longer attached to that database. This happens after some restores and after account-level changes.

In the database section of your control panel, look at the database and confirm your user is listed against it with full privileges. If it is not, add it. This costs nothing and rules out an entire category of cause in about a minute.

3. The database server is temporarily unavailable

If the credentials are definitely right, the next question is whether MySQL is answering at all. A short, self-resolving outage produces exactly this error, and so does a site hitting a resource limit.

A quick way to test the connection independently of WordPress: create a file called dbtest.php in your site root with the following, filling in your own values.

<?php
$link = @mysqli_connect('localhost', 'DB_USER', 'DB_PASSWORD', 'DB_NAME');
if (!$link) {
    die('Failed: ' . mysqli_connect_error());
}
echo 'Connected.';

Visit yourdomain.com/dbtest.php. "Connected." means your credentials are fine and the problem lies inside WordPress. A failure message tells you precisely why the connection is being refused, which is far more useful than the generic front-end error.

4. Traffic or a plugin is exhausting the connection limit

Databases accept a finite number of simultaneous connections. If a site is being hammered, or a badly written plugin is opening connections and not closing them, new requests are refused — and the error comes and goes rather than staying constant.

The tell is intermittency. If the site works on a refresh, fails a minute later, then works again, this is very likely what is happening. Deactivating recently installed plugins is the fastest way to test it; if the site steadies, reactivate them one at a time until the error returns.

5. A database table is corrupted

Rare, but it does happen, usually after an unclean shutdown. The distinctive sign is a different message in wp-admin from the one on the front end, mentioning that the database may need repairing.

WordPress has a built-in repair tool that is switched off by default. Add this line to wp-config.php, above the line that says it has stopped editing:

define( 'WP_ALLOW_REPAIR', true );

Then visit yourdomain.com/wp-admin/maint/repair.php and choose "Repair Database". You do not need to be logged in, which is exactly why the next step matters:

phpMyAdmin can do the same job: select the database, tick the affected tables, and choose "Repair table" from the dropdown at the bottom.

If none of that fixed it

Two things are worth doing before you ask for help, because they turn a vague report into a solvable one.

Turn on debugging. In wp-config.php, set:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );

Reload the site, then read wp-content/debug.log. Switch all three back off afterwards — a public site should never display or accumulate debug output.

Note what changed. An update, a migration, a plugin install, a password reset, a traffic spike. The answer to "what changed just before this started" identifies the cause more often than any diagnostic does.

With the log entry and that answer, open a ticket — those two pieces of information are usually enough for us to find it from our side straight away.