Error Establishing a Database Connection in WordPress: How to Fix It

One minute your site is fine. The next, every page shows one bold line of text: “Error establishing a database connection.” No header, no menu, no content. Just that sentence, on the homepage, on every blog post, and usually on wp-admin too.

The “error establishing a database connection” message in WordPress means PHP tried to talk to your MySQL or MariaDB database and got nothing back. Your files are fine. Your content is almost certainly fine. WordPress just can’t reach the place where all of that content lives. The good news is that there are only four real causes, and you can work through them in order in about 20 minutes.

What Does “Error Establishing a Database Connection” Actually Mean?

“Error establishing a database connection” means WordPress could not log in to its database server using the details stored in wp-config.php. Every WordPress page is built from database content, so when that connection fails, WordPress has nothing to render and shows this error instead of your site.

WordPress needs four pieces of information to connect: the database name, the database username, the password, and the database host. All four live in wp-config.php in your site’s root folder. If any one of them is wrong, or if the database server itself is down or overloaded, the connection fails.

One useful clue: visit yoursite.com/wp-admin. If the admin area shows a different message, “One or more database tables are unavailable. The database may need to be repaired,” then the connection works and the database itself is damaged. That skips you straight to the repair step below.

The 4 Causes, and How to Tell Which One You Have

The WordPress database connection error almost always comes from wrong credentials, a down or overloaded database server, a corrupted database, or (rarely) damaged core files. The timing of the error is the fastest way to tell them apart: what changed right before it appeared?

Before touching anything, take a backup of your files and, if your hosting panel can still reach it, the database. Every fix below is low-risk, but editing wp-config.php without a copy of the original is how a 20-minute fix turns into a two-hour one.

Fix 1: Check Your wp-config.php Database Credentials

Wrong database credentials in wp-config.php are the most common cause of this error, and fixing them takes five minutes. Compare the four database values in wp-config.php against the real database details in your hosting panel, and correct any that don’t match exactly.

Kinsta’s troubleshooting guide calls incorrect login credentials “by far the most common reason” for the error, and that matches the usual timeline: the site worked, then someone migrated it, changed hosts, or reset the database password, and the error showed up immediately after.

Open wp-config.php through your host’s File Manager or FTP and find these lines:

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

Now check each one in your hosting panel. On cPanel, that’s the “MySQL Databases” screen:

1. DB_NAME: Confirm a database with this exact name exists. On shared hosting, names usually carry a prefix, like cpaneluser_wp123, and missing that prefix is a classic mistake.
2. DB_USER: Confirm the user exists and, just as important, is actually assigned to that database with “All Privileges.” A valid user who isn’t attached to the database still can’t connect.
3. DB_PASSWORD: You can’t view the existing password, so reset it in the panel and paste the new one into wp-config.php. Avoid single quotes in the password, since wp-config.php wraps the value in single quotes and a stray one breaks the line.
4. DB_HOST: localhost works on most shared hosts, but not all. Some managed and cloud hosts use a separate hostname, an IP address, or a custom port like localhost:3307. Your host’s documentation or the database section of your panel lists the right value.

Save the file and reload the site. If you recently moved the site, this is also a good moment to read through a proper WordPress migration process, because mismatched credentials are one of the most predictable migration failures.

How Do I Test the Database Connection Directly?

A tiny PHP test file tells you whether the database credentials work, independent of WordPress. If the test file connects but WordPress still shows the error, the credentials are fine and the problem is elsewhere.

Create a file called dbtest.php in your site root with this code, replacing the four values with the ones from wp-config.php:

<?php
$conn = mysqli_connect( 'localhost', 'your_database_user', 'your_database_password', 'your_database_name' );
if ( ! $conn ) {
    die( 'Connection failed: ' . mysqli_connect_error() );
}
echo 'Connected successfully.';
mysqli_close( $conn );

Visit yoursite.com/dbtest.php. “Access denied for user” means the username or password is wrong. “Unknown database” means the database name is wrong. “Connection refused” or a timeout points to the host value or a server problem. Delete the file as soon as you’re done, since it contains your database password in plain text.

Fix 2: Check Whether the Database Server Is Down

If the credentials are correct and the error still appears, the database server itself is probably down or refusing connections. Log in to phpMyAdmin from your hosting panel: if phpMyAdmin also fails to connect, the problem is on the host’s side, and only the host can fix it.

On shared hosting, one server runs databases for hundreds of accounts. A crash, a maintenance window, or another customer hammering the server can all take MySQL offline for everyone on it. Check your host’s status page first, then open a support ticket with the exact error message and the time it started. That’s faster than guessing.

Why Does the Error Come and Go?

An intermittent “error establishing a database connection” usually means the database is hitting a connection limit, not that anything is misconfigured. Shared hosting plans cap how many simultaneous database connections one account can open, and a traffic spike, a bot crawl, or a plugin running heavy queries can push past that cap for a few minutes at a time.

The real fix here is reducing how often WordPress hits the database at all:

• Turn on page caching. A cached page is served as static HTML with zero database queries. This is the single biggest lever for connection-limit problems.
• Block junk bot traffic. Aggressive crawlers and login brute-force attempts all open database connections. A firewall or Cloudflare in front of the site cuts most of it.
• Clean up the database. Bloated autoloaded options and years of revisions make every query slower, which holds connections open longer. A WordPress database cleanup helps here more than most people expect.
• Ask the host about limits. Ask what your max_user_connections limit is. If the site genuinely outgrew the plan, upgrading is the honest fix, not another plugin.

Fix 3: Repair a Corrupted WordPress Database

WordPress has a built-in database repair tool that fixes most corrupted tables in a couple of minutes. You enable it with one line in wp-config.php, run it from a special URL, and then remove the line again immediately.

Add this line to wp-config.php, just above the line that says “That’s all, stop editing!”:

define( 'WP_ALLOW_REPAIR', true );

Then visit yoursite.com/wp-admin/maint/repair.php and click “Repair Database.” The “Repair and Optimize Database” option does more work and takes longer, but the plain repair is enough to get the site back online.

The WordPress repair page does not require a login, so anyone who knows the URL can load it while the constant is active. Remove the WP_ALLOW_REPAIR line as soon as the repair finishes. Leaving it in place is an open door.

If you have SSH access and WP-CLI, wp db repair does the same job from the command line without exposing any URL. Alternatively, phpMyAdmin lets you select all tables and choose “Repair table” from the dropdown.

Fix 4: Replace Damaged WordPress Core Files

Damaged WordPress core files are the least common cause, but when credentials, the server, and the database all check out, replacing the core files is the next step. A fresh copy of the wp-admin and wp-includes folders overwrites anything corrupted without touching your content, themes, or plugins.

1. Download the same WordPress version your site runs from wordpress.org.
2. Unzip it on your computer and delete the wp-content folder and wp-config-sample.php from the download, so you can’t overwrite your own.
3. Upload the remaining files over FTP, overwriting the existing ones.

If core files were damaged by a hack rather than a botched update, replacing them only treats the symptom. Look for the other warning signs covered in signs your WordPress site is hacked before assuming the job is done.

How to Stop the Database Connection Error From Coming Back

Preventing the WordPress database connection error comes down to three habits: keep working off-site backups, update credentials carefully during migrations, and don’t run a busy site on hosting that can’t handle its traffic. Most repeat cases trace back to one of those three.

A daily backup that includes the database, stored somewhere other than the same server, turns a corrupted database from a disaster into a ten-minute restore. Uptime monitoring tells you the site is down before a customer does. And if the error keeps showing up during normal traffic, the hosting plan is the problem. Adding caching plugins on top of an overloaded server only delays the next outage.

If the site shows a blank page instead of this message, that’s a different problem with a different fix. The WordPress white screen of death guide covers that one.

The bottom line: “error establishing a database connection” looks scary, but it’s one of the most fixable WordPress errors there is. Check the credentials first, confirm the server is up second, repair the database third. Most cases end at step one.

Frequently Asked Questions