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 you almost no detail about what actually went wrong.

In most sites I build, this error traces back to one of three places: a typo or outdated credential in wp-config.php, a database server that’s temporarily overloaded or down, or — less often — a corrupted database table. The good news is that none of these require deep technical skill to check, and you can usually narrow it down in a few minutes.

Quick Answer

A WordPress database connection error almost always means your site can’t reach or authenticate with its MySQL database. Start by checking the database credentials in wp-config.php against what your host’s control panel shows, then confirm the database server itself is actually running. If both check out, the database may need repairing.

Why This Matters

Every page on a WordPress site — posts, pages, menus, settings — is stored in a MySQL database and pulled in on every single page load. When WordPress can’t open that connection, it can’t render anything at all, so the entire site goes down at once rather than just one page or feature. Visitors see a broken, unbranded error message, and if it’s not resolved quickly it also affects search engine crawling, since Google treats a database error the same as any other server failure.

The upside is that this error is almost never caused by your theme, plugins, or content. It sits one layer below all of that, in the connection between WordPress and its database, which is exactly why the fix list is short and specific. WordPress’s own documentation on common WordPress errors confirms the same three root causes covered below.

Step-by-Step Instructions

1. Check Your wp-config.php Credentials

Connect to your site 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 value against the database details shown in your hosting control panel (usually under a “Databases” or “MySQL” section). A single mistyped character in any of these — especially after a password reset or a site migration — is the single most common cause of this error.

DB_HOST trips people up most often. Many hosts use localhost, but some managed hosting environments require a specific hostname or IP address instead, which your host’s documentation or support team can confirm.

2. Confirm the Database User Still Has Permissions

In your hosting control panel, check that the database user listed in DB_USER is still assigned to the database in DB_NAME with full privileges. It’s easy for this link to get quietly removed during a hosting migration, a security cleanup, or a bulk account change — the user and database can both still exist while no longer being connected to each other.

3. Check Whether the Database Server Is Actually Running

If your credentials are correct, the next possibility is that the MySQL server itself is temporarily down or overloaded — this happens more often on shared hosting during traffic spikes. Check your host’s status page, or contact support and ask directly 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 just need to wait for it to come back or ask your host to restart the service.

4. Repair the Database

If the server is up and credentials are correct but the error persists, a database table may have become corrupted. WordPress has a built-in repair tool you can enable by adding 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 in your browser. You’ll see options to repair or repair-and-optimise the database — choose the optimise option, let it finish, and then remove the line you just added from wp-config.php. Leaving this line in place would let anyone reach that repair page, so it should only be active for the few minutes you need it.

5. Restore From a Recent Backup if Nothing Else Works

If none of the steps above resolve it, the safest next move is restoring your most recent backup rather than continuing to experiment on a live, broken site. This is one of the clearest reasons to keep a recent backup of your WordPress website on hand at all times — a database-level failure is exactly the scenario a backup is meant to cover.

Practical Tips

• Before editing wp-config.php, make a copy of it first — 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 to what changed.
• Keep your database credentials in a password manager rather than memory. In my experience, most database connection errors after a migration come down to a credential that was typed from memory instead of copied exactly.

Common Mistakes

• Assuming the error means your whole site is gone — in almost every case, the 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, which turns a single typo into a second problem to fix.
• Contacting support about “the site is down” without mentioning the specific database error message, which slows down diagnosis on their end.

When to Use This vs Alternatives

The steps above are the right first move any time you see this specific error message. If your site instead shows a blank white screen with no error text at all, that’s usually a PHP issue rather than a database one — see how to fix the White Screen of Death in WordPress for that case. If you’re instead getting a 500 status code with a different message, fixing the WordPress 500 Internal Server Error covers that separately. And if your site is working but has been running slowly, it’s worth learning how to clean up and optimise your WordPress database as routine maintenance, the same kind of foundational care covered in the step-by-step guide to building a WordPress website.

Conclusion

A database connection error looks alarming but is 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.