Error Establishing a Database Connection in WordPress: Fixes and a Custom Error Page

Back in 2007, while upgrading WordPress, I learned a neat trick: put a file called db-error.php in wp-content, and WordPress shows your own friendly message instead of a bare database error. It still works in 2026. But first, here’s how to fix the dreaded error establishing a database connection message itself.

Quick answer: This error means WordPress can’t talk to its MySQL or MariaDB database. Check that DB_NAME, DB_USER, DB_PASSWORD and DB_HOST in wp-config.php match your hosting database details, make sure the database server is running (ask your host), and repair corrupted tables with WP_ALLOW_REPAIR. Add a custom wp-content/db-error.php so visitors see a helpful message during outages.

How to fix error establishing a database connection

1. Check wp-config.php credentials

Open wp-config.php in your host’s file manager and compare DB_NAME, DB_USER, DB_PASSWORD and DB_HOST with the database details in your hosting panel. DB_HOST is often localhost but some hosts use a hostname or port.

2. Check the database server

If the credentials are correct, the database server may be down or overloaded. Check your host’s status page or contact support. On shared hosting, traffic spikes can hit connection limits.

3. Repair the database

1. Add define('WP_ALLOW_REPAIR', true); to wp-config.php.
2. Visit yoursite.com/wp-admin/maint/repair.php and click Repair Database.
3. Remove the line afterwards; the page doesn’t require login.

4. Reset the database user password

In your hosting panel, reset the MySQL user’s password and update wp-config.php to match.

5. Restore from backup

If tables are badly damaged, restore a recent backup. See how to back up and restore a WordPress database.

Create a custom db-error.php page

Create a file named db-error.php in wp-content with simple HTML (it can’t use WordPress functions because the database is down):

<?php header('HTTP/1.1 503 Service Temporarily Unavailable'); header('Retry-After: 600'); ?>
<!doctype html>
<html><head><title>Back soon</title></head>
<body><h1>We'll be right back</h1>
<p>The site is having a temporary database problem. Please check again in a few minutes.</p></body></html>

The 503 status tells search engines the outage is temporary, which protects your rankings.

Prevent it happening again

• Keep regular off-site backups.
• Use caching to reduce database load.
• Optimize your WordPress database occasionally.
• Upgrade hosting if you often hit connection limits.

FAQ

Why does the error appear only sometimes?

Usually the database server is overloaded or hitting connection limits during traffic spikes.

Can a plugin cause this error?

Rarely; it’s usually credentials, a server problem or corrupted tables.

Does db-error.php survive WordPress updates?

Yes, updates don’t touch files you add to wp-content.