Fix 'Error Establishing a Database Connection' in WordPress

Few WordPress messages stop you cold like "Error establishing a database connection." The whole site — front end and wp-admin — goes blank behind that one line. The good news: it's almost always one of a handful of causes, and most take only a few minutes to fix once you know where to look. Here's the exact order we work through it on Getwebup support.

What the error actually means

WordPress stores your posts, pages, users and settings in a MySQL/MariaDB database. On every request it reads the connection details from wp-config.php and opens a connection to that database. This error means the handshake failed — WordPress reached out, and the database didn't answer the way it expected.

So it's almost never your theme or a plugin. It's one of four things: the credentials are wrong, the database server isn't responding, the database itself is corrupted, or the user account lost its access. We'll rule them out in that order.

Quick checks before you change anything

• Is only your site down, or the server too? Load another site on the same hosting account. If everything is down, it's a server-side issue — skip to the database-server section.
• Did something just change? A migration, a host move, a search-and-replace, an edit to wp-config.php, or a "repair" plugin are the usual triggers.
• Does wp-admin show a different message? If it says "One or more database tables are unavailable. The database may need to be repaired," that points to corruption — jump to the repair section.

The usual causes — and how to fix each

1. Wrong database credentials in wp-config.php

This is the most common cause, especially right after a migration. Open wp-config.php in your site root (cPanel: Files → File Manager → public_html, or over SFTP at /home/USER/public_html/wp-config.php) and find these four lines:

define( 'DB_NAME', 'your_db_name' );
define( 'DB_USER', 'your_db_user' );
define( 'DB_PASSWORD', 'your_db_password' );
define( 'DB_HOST', 'localhost' );

Every value has to match a real database on the server. Confirm them in cPanel → Databases → MySQL Databases. Two things trip people up:

• On most shared/cPanel hosts the real names are prefixed with your account — e.g. cpuser_wp, not just wp. Copy them exactly.
• If you're unsure of the password, don't guess. In MySQL Databases, set a new password for the user, then paste that same value into DB_PASSWORD.

Leave DB_HOST as localhost unless your host says otherwise (a few use 127.0.0.1 or a dedicated hostname). Save and reload your site.

2. The database server is down or overloaded

If the credentials are definitely right but the error persists — and neighbouring sites are down too — the database service itself may be stopped or swamped. On shared hosting you can't restart it yourself; open a ticket and your host will check the service and load. On a VPS where you have root, check and restart it:

sudo systemctl status mariadb
sudo systemctl restart mariadb   # or: sudo systemctl restart mysql

If it won't start, you're usually looking at a crash or a full disk. Check free space with df -h — a database can't write when the disk is 100% full, and that alone throws this exact error. Clear space (old logs, stale backups) and start the service again.

3. A corrupted database

If the front end shows the connection error but /wp-admin says a table "may need to be repaired," WordPress has a built-in tool. Add this line to wp-config.php, just above the /* That's all, stop editing! */ comment:

define( 'WP_ALLOW_REPAIR', true );

Now visit https://yourdomain.com/wp-admin/maint/repair.php and click Repair Database. When it finishes, remove that line again — leaving it in lets anyone run the tool without logging in. Prefer phpMyAdmin? Open cPanel → phpMyAdmin, select the database, tick the affected tables, and choose Repair table from the "With selected" dropdown.

4. The database user lost its privileges

Sometimes the user exists and the password is right, but it's no longer assigned to the database — common after restoring a backup or recreating a user. In cPanel → MySQL Databases → Add User to Database, attach the user to the database and grant ALL PRIVILEGES. Then retry.

5. Too many connections

On a busy site or an under-powered plan you can hit the connection limit. The tell-tale is an intermittent error — fine most of the time, failing under load. Short term, a restart clears stuck connections. Longer term, add caching (so fewer requests reach the database), fix any slow or duplicating plugin, or move to a plan with more resources.

A safe way to test the connection directly

To prove whether the credentials in wp-config.php actually work, drop a tiny test file next to it — say dbtest.php:

<?php
$link = mysqli_connect('localhost', 'DB_USER', 'DB_PASSWORD', 'DB_NAME');
echo $link ? 'Connected fine.' : 'Failed: ' . mysqli_connect_error();

Load https://yourdomain.com/dbtest.php. "Connected fine" means your credentials are correct and the problem is elsewhere (corruption or privileges). A failure message tells you exactly what's wrong. Delete the file the moment you're done — never leave database credentials in a public script.

How to stop it happening again

• Keep real backups. Automated daily backups of files and database turn a bad migration or corruption into a five-minute restore instead of a crisis.
• Change credentials in one place. If you rotate the database password, update wp-config.php in the same sitting.
• Add caching. A page cache keeps most visitors from ever touching the database, which prevents the "too many connections" version of this error.
• Watch disk space. Alert yourself before the disk fills; a full disk silently breaks the database.
• Right-size your plan. If you hit connection limits often, that's the plan talking — a VPS or a larger plan gives the database room to breathe.

Work through the causes in order and you'll usually find it in the first two. If you're on Getwebup hosting and you'd rather we just handle it, open a ticket with your domain and we'll check the database service, credentials and integrity for you.