How to Fix a WordPress Database Connection Error

You load your site and instead of your homepage you get a plain white screen with one line of text: “Error establishing a database connection.” No styling, no menu, nothing — just that sentence sitting on a blank page. It’s one of the more alarming errors WordPress can throw, mostly because it gives almost no detail about what actually went wrong, and unlike most fatal errors, WordPress can’t do anything automatic about it.

Why WordPress Can’t Self-Heal This One

Since WordPress 5.2, the platform has shipped a built-in fatal-error protection system: when a plugin or theme throws a fatal PHP error, WordPress catches it, keeps the site from staying fully broken, and emails the site admin a special recovery-mode link to fix things from a stripped-down admin screen. It’s genuinely useful — except it can’t help here. A database connection failure happens too early in WordPress’s bootstrap process, before the code that catches fatal errors and sends that recovery email has even loaded. That’s the real reason this error feels more alarming than a typical plugin crash: there’s no automatic safety net, and both the front end and the admin dashboard go dark together rather than just one broken feature.

The Three Places This Actually Comes From

In most sites I build, this error traces back to one of three places, roughly in order of likelihood:

1. A Typo or Outdated Credential in wp-config.php

Connect via FTP or your hosting file manager and open wp-config.php in the root folder. Near the top you’ll find four constants: DB_NAME, DB_USER, DB_PASSWORD, and DB_HOST. Compare each against the database details in your hosting control panel’s “Databases” or “MySQL” section. A single mistyped character — especially after a password reset or a site migration — is the single most common cause. DB_HOST trips people up most: many hosts use localhost, but some managed environments require a specific hostname or IP address instead, which your host’s documentation or support team can confirm. While you’re in there, also check the database user in DB_USER is still assigned to the database in DB_NAME with full privileges — it’s easy for that link to get quietly severed during a hosting migration or security cleanup, with both the user and database still existing but no longer connected to each other.

2. The Database Server Itself Is Down or Overloaded

If credentials check out, the MySQL (or, on many modern hosts, MariaDB — a drop-in-compatible fork most shared hosting has quietly switched to) server may be temporarily down or overloaded, which happens more often on shared hosting during traffic spikes. Check your host’s status page or contact support directly and ask whether the database server for your account is currently up. If it’s a shared-resource issue on their end, there’s nothing to fix in WordPress itself — you wait for it to come back or ask them to restart the service.

3. A Corrupted Database Table

Less common, but if the server is up and credentials are correct and the error persists, a table may have become corrupted. WordPress has a built-in repair tool: add this line to wp-config.php, just above /* That's all, stop editing! */:

define( 'WP_ALLOW_REPAIR', true );

Then visit yoursite.com/wp-admin/maint/repair.php in your browser, choose the repair-and-optimise option, let it finish, and remove the line you just added. Leaving it in place makes that repair page reachable by anyone who finds the URL, so it should only be active for the few minutes you need it.

If None of That Works

The safest next move is restoring your most recent backup rather than continuing to experiment on a live, broken site — this is exactly the scenario a recent backup is meant to cover. WordPress’s own documentation on common WordPress errors confirms the same three root causes covered above, and it’s worth reading if any of these steps turn up something unexpected.

Practical Tips

• Copy wp-config.php before editing it — if a fix doesn’t work, you can revert instantly instead of guessing what the file looked like before.
• If the error appeared right after a plugin update or hosting change, check your host’s activity log first — it often points straight at what changed.
• Keep database credentials in a password manager rather than memory. In my experience, most connection errors after a migration come down to a credential typed from memory instead of copied exactly.

Common Mistakes

• Assuming the error means your whole site is gone — in almost every case, content is untouched and the fix is a configuration or server issue, not data loss.
• Leaving WP_ALLOW_REPAIR set to true after running the repair tool, which leaves the repair page publicly accessible.
• Editing wp-config.php on a live server without a backup copy, turning a single typo into a second problem to fix.
• Contacting support about “the site is down” without mentioning the specific error message, which slows down diagnosis on their end.

Telling This Error Apart From Similar Ones

The steps above are the right first move any time you see this specific message. A blank white screen with no error text at all is usually a PHP issue rather than a database one — see how to fix the White Screen of Death for that case, which recovery mode does catch. A 500 status code with a different message means fixing the WordPress 500 Internal Server Error covers that separately. And if the site is working but running slowly rather than down, cleaning up and optimising the database is routine maintenance worth doing before it becomes an emergency — the same kind of foundational care covered in the step-by-step guide to building a WordPress website.

A database connection error looks alarming precisely because WordPress’s built-in fatal-error protection can’t reach it — but it’s almost always a credentials or server-availability issue rather than lost content. Check wp-config.php against your host’s actual database details first; it resolves the majority of cases on its own.