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

"Error establishing a database connection" means WordPress couldn't talk to MySQL, so it can't load any content at all. The good news: unlike most WordPress errors, there are only a few possible causes, and you can work through them in about ten minutes.

Cause 1: Wrong database credentials in wp-config.php

This is the usual culprit after a migration, a host change, or a password reset in your hosting panel. Open wp-config.php and find these four lines:

define( 'DB_NAME', 'example_wp' );
define( 'DB_USER', 'example_user' );
define( 'DB_PASSWORD', 'the-password' );
define( 'DB_HOST', 'localhost' );

Compare each value with your hosting panel (in cPanel: MySQL Databases). Things to check:

• Prefixes: on shared hosting, database and user names usually carry your account prefix, e.g. acct123_wp, not wp.
• The user must be assigned to the database with all privileges. Creating a user isn't enough. In cPanel, use "Add User to Database".
• DB_HOST isn't always localhost. Some hosts use a separate database server, such as mysql.example-host.com, or a custom port like localhost:3307. Check your host's docs.
• Special characters in the password: a single quote inside a single-quoted PHP string breaks the line. Reset the password to one without quotes or backslashes to rule this out.

Test the credentials outside WordPress

Create a file called db-test.php in the site root with the same values:

<?php
$link = mysqli_connect( 'localhost', 'example_user', 'the-password', 'example_wp' );
if ( ! $link ) {
    die( 'Connection failed: ' . mysqli_connect_error() );
}
echo 'Connected successfully';
mysqli_close( $link );

Open yoursite.com/db-test.php in your browser. The error message is far more specific than WordPress's:

• Access denied for user: wrong username or password, or the user isn't assigned to the database.
• Unknown database: the database name is wrong, or the database doesn't exist (a failed migration import).
• Connection refused or No such file or directory: the MySQL server isn't running, or DB_HOST is wrong.
• Too many connections: the server is overloaded. See cause 2.

Delete db-test.php immediately afterwards. It contains your database password in plain text.

Cause 2: The database server is down or overloaded

If the credentials were working yesterday and nothing changed, the MySQL server itself is the likely problem.

• Shared hosting: check your host's status page and contact support. You can't restart MySQL yourself.
• VPS or dedicated server: check and restart the service:

sudo systemctl status mysql     # or mariadb
sudo systemctl restart mysql
sudo tail -n 50 /var/log/mysql/error.log

If MySQL keeps crashing, the error log usually says why. On small VPS plans the most common cause is running out of RAM: the kernel's OOM killer stops MySQL under load. You'll see it in dmesg | grep -i oom. The fix is adding swap, lowering MySQL's memory settings, or upgrading the server.

"Too many connections" errors or the error appearing only at busy times point to traffic or bots exhausting the connection limit. Page caching and blocking bad bots (see my Cloudflare WAF rules for WordPress) often fix this without a server upgrade.

Cause 3: Corrupted database tables

A crash or full disk can corrupt tables. WordPress has a built-in repair tool. Add this line to wp-config.php:

define( 'WP_ALLOW_REPAIR', true );

Then visit yoursite.com/wp-admin/maint/repair.php and click Repair Database. This page doesn't need a login, so remove the line from wp-config.php as soon as you're done.

With WP-CLI you can do the same from the command line:

wp db check
wp db repair

Cause 4: The disk is full

MySQL can't write when the disk is full, and the result can look exactly like a connection error. Check usage in your hosting panel, or with df -h on a server. Usual suspects: old backups stored on the same server, huge log files, and debug.log files that were left running for months.

Cause 5: Multisite domain mismatch

On a multisite network, the domain in wp-config.php (DOMAIN_CURRENT_SITE) must match the values in the wp_site and wp_blogs tables. After a domain change, a mismatch can produce this same error even though the credentials are correct.

If none of these fit: check for tampering

If wp-config.php was changed and nobody on your team touched it, treat the site as compromised. Attackers sometimes change files during an infection. Check the file's modification date, and look for unfamiliar PHP files in the root and wp-content/uploads. My hacked site cleanup guide walks through what to look for.

Preventing it

• Keep off-server backups of both files and database, so a full disk or a dead server isn't a disaster.
• Set up uptime monitoring (UptimeRobot, Better Stack and others have free tiers) so you hear about outages before your customers do.
• On a VPS, monitor memory and disk, and configure swap.