Your site shows one line of plain text on a white background: Error establishing a database connection. No design, no menu, no admin login. The whole site, gone.
Here’s the fastest path back, in order. If you’re in a hurry, do the first three steps and stop reading.
Rather not do this yourself? We fix WordPress emergencies. Get in touch — phone, email, live chat, whatever’s fastest for you. Or see what WordPress repair covers first.
Everyone else: start here.
What the error actually means
WordPress is running. PHP is working. Your server answered the request. That’s already useful information — it rules out a large category of problems.
What failed is one specific thing: WordPress tried to open a connection to MySQL and didn’t get one. That’s it. The message tells you the conversation didn’t happen. It doesn’t tell you why, and the four possible reasons are very different problems with very different fixes:
The credentials are wrong — WordPress is using a username, password, database name or host that MySQL rejects
The database server isn’t reachable — MySQL is down, restarting, or refusing new connections
The connection limit is exhausted — MySQL is running fine, but has no free connection slots left for you
The database itself is damaged — the connection works, but a table is corrupt or missing
Almost every guide online starts with number one. That’s the right place to start only in one specific situation, and it’s probably not yours.
Do this first: has anything changed?
Before you touch a single file, answer one question.
Was the site working yesterday, and did nobody edit wp-config.php, migrate the site, or change hosting?
If yes — your credentials are fine. Skip the wp-config check entirely. Database credentials do not rot. They don’t expire on their own, and they don’t change while you sleep. A file that worked on Sunday works on Monday unless something rewrote it.
This one question saves most people twenty minutes of staring at a file that isn’t the problem.
Check credentials first only if: you just migrated the site, you just changed hosts, you just restored a backup, someone edited wp-config.php, or you reset the database password in your hosting panel. In those cases, jump to the credentials section below — that genuinely is your most likely cause.
Everyone else: the problem is on the server side, and the next step tells you which kind.
Step 1: Can the admin load?
Try yourdomain.com/wp-admin.
If the admin shows the same error — the database is unreachable across the board. Server-side problem. Continue to step 2.
If the admin shows a different message — something like “one or more database tables are unavailable, the database may need to be repaired” — then your connection is working. This isn’t a connection problem at all. It’s a corrupt table. Jump ahead to the section on repair, and read the warning in it before you run anything.
That’s a meaningful fork, and it takes ten seconds to check.
Step 2: Is it just you, or is it the server?
This is the step that determines whether you can fix this yourself.
Check your host’s status page. Most have one. A database outage affecting a shared server won’t be listed under your account — it’ll be listed there.
Check another site on the same hosting account, if you have one. Both down means the server. One down means your site.
Check your disk quota. This is the cause nobody expects, and it’s more common than any credential problem.
When a hosting account hits its storage limit, MySQL cannot write — and a database that cannot write often refuses connections outright. The site was fine for months, nothing changed, and then it fell over at 4 a.m. because a backup plugin filled the last free gigabyte.
Look in your hosting panel for disk usage. If you’re at or near the limit, that’s your answer, and the fix is deleting files, not debugging PHP. The usual suspects: old backups sitting in wp-content, an error_log file that grew to several gigabytes, and cached image sizes from a media library nobody has pruned.
Check whether MySQL is running, if you have SSH access:
systemctl status mysql
On managed or shared hosting you won’t have this. That’s fine — your host does, and that’s what step 3 is for.
Step 3: The connection limit — the cause most guides never mention
Here’s the scenario nobody’s guide covers, and it’s one of the most common real-world causes on a busy site.
MySQL allows a fixed number of simultaneous connections. On shared hosting that number is often low, and it’s shared across every process your account runs. When the limit is reached, MySQL doesn’t crash — it simply refuses the next connection. WordPress receives that refusal and prints Error establishing a database connection.
The site then recovers on its own a minute later, when connections free up. Then it happens again during the next traffic spike.
The tell: the error is intermittent. It’s there, you refresh, it’s gone. If you’ve been trying to explain to yourself why the site is “randomly” down for two minutes at a time, this is almost certainly why — and no amount of checking wp-config.php will ever find it.
What exhausts connections in practice:
A traffic spike — including a bot crawling you aggressively, which is far more common than an actual traffic spike
A slow query holding connections open — one unindexed query on a large
wp_postmetatable can tie up connections long enough to starve everything elseWooCommerce under load — cart and checkout can’t be cached, so every one of those requests opens a database connection. Fifty people in checkout is fifty simultaneous connections that a cache would otherwise have absorbed
A plugin that opens connections and doesn’t close them properly
If your checkout is the thing that keeps falling over, this and WooCommerce checkout performance are the same underlying story: uncacheable pages running the full stack on every request.
What to do about it: this is a hosting conversation, not a WordPress one. Ask your host two specific questions — what is max_connections on my server, and am I hitting it? They can see it in the logs immediately. The answer is either “raise the limit,” “you need a plan with dedicated resources,” or “you have a query problem” — and knowing which one saves you from buying the wrong solution.
Step 4: Test the connection directly
If you’re not sure whether the problem is WordPress or MySQL itself, take WordPress out of the equation.
Create a file called dbtest.php in your site root:
<?php
$link = mysqli_connect('localhost', 'db_user', 'db_password', 'db_name');
if (!$link) {
die('Failed: ' . mysqli_connect_error());
}
echo 'Connected successfully.';
Fill in the four values from wp-config.php — DB_HOST, DB_USER, DB_PASSWORD, DB_NAME — and load yourdomain.com/dbtest.php.
The result is unambiguous:
“Connected successfully” → your credentials are correct and MySQL is reachable. The problem is inside WordPress: a corrupt table, or a plugin interfering before the connection is used
“Access denied for user…” → credentials genuinely are wrong. Go to step 5
“Can’t connect to MySQL server…” → the server isn’t reachable or isn’t running. Back to step 2, and this is now a host ticket
“Too many connections” → step 3 was your answer
Delete this file the moment you’re done. It contains your database password in plain text, in your web root, readable by anyone who guesses the filename.
Step 5: Credentials — if you got here legitimately
Only if you migrated, changed hosts, restored a backup, or the test above said access denied.
Open wp-config.php and check four lines:
define('DB_NAME', 'your_database_name');
define('DB_USER', 'your_database_user');
define('DB_PASSWORD', 'your_password');
define('DB_HOST', 'localhost');
What actually goes wrong here, in order of frequency:
DB_HOST isn’t localhost. This is the single biggest migration gotcha. localhost works on most shared hosting and is wrong nearly everywhere else. Managed hosts, cloud providers and any setup with a separate database server need a specific hostname or IP — sometimes with a port, like mysql.yourhost.com:3306. Your host’s control panel shows the correct value. Guessing wastes time.
The database user isn’t attached to the database. On cPanel-style hosting, creating a user and creating a database are two separate actions, and a third action links them. Skip the third and you get access denied with credentials that look perfectly correct.
The prefix. Many hosts prepend your account name automatically, so the database you created as wordpress actually exists as acct123_wordpress, and the user as acct123_wpuser.
A stray character. A trailing space inside the quotes, or a password containing $ in a double-quoted string — where PHP tries to interpolate it as a variable. Use single quotes.
If you’re unsure the password is right, reset it in your hosting panel and paste the new one into wp-config.php. Resetting is faster than verifying.
Step 6: A corrupt table — and a serious warning
If the connection works but the admin reports unavailable tables, you have corruption. This usually follows an unclean shutdown, a crashed server, or a disk that filled up mid-write.
Every guide will now tell you to add this to wp-config.php:
define('WP_ALLOW_REPAIR', true);
…and visit yourdomain.com/wp-admin/maint/repair.php.
Read this before you do it on a store.
That page is accessible without logging in. That’s deliberate — you often can’t log in when the database is broken — but it means that for as long as the constant is in your config file, anyone who knows the URL can trigger a repair operation on your database. It is a well-known URL.
More importantly: REPAIR TABLE is a destructive operation. On a corrupt table it can and does discard rows it can’t recover. On wp_posts that might mean a lost revision. On wp_woocommerce_order_items it means orders you can no longer fulfil, with no record of what was in them.
So, in order:
Take a database backup first — even a broken one.
mysqldumpif you have SSH, or the export function in phpMyAdmin. If the repair goes badly, this is the only thing standing between you and permanent data lossAdd the constant, run the repair
Remove the constant from
wp-config.phpimmediately afterwards. Not later. Not tomorrow
On a WooCommerce store with real orders in it, I’d genuinely rather you called your host first and asked them to run the repair with proper backups in place. The five minutes you save doing it yourself is not worth the version of this that goes wrong.
Step 7: When the database is fine and WordPress still fails
Occasionally everything above checks out — the test file connects, tables are intact, the server is healthy — and the error persists.
Two remaining causes:
A corrupted core file. Specifically wp-db.php or the database drop-in at wp-content/db.php, which some caching and performance plugins install. Delete wp-content/db.php if it exists and see if the site returns. Then reinstall core with wp core download --force, which replaces core files without touching your content.
A plugin hard-coding connection details. Rare, but it happens with some caching, backup and multi-site plugins after a migration. Rename wp-content/plugins to plugins_off via FTP. If the site comes back, rename it back and re-enable plugins one at a time.
Step 8: If it keeps coming back
A database connection error that returns is a capacity problem, not a bug. Fixing it repeatedly is not fixing it.
Find out whether you’re hitting max_connections. Your host can answer this in minutes. This is the first question, not the last.
Look at what’s actually querying. A slow query log will show you within a day whether one plugin is responsible. Query Monitor on a staging copy will show you the same thing faster.
Check your wp_options autoload size. Every single page load reads every autoloaded option. When that array is measured in megabytes, every request does more database work than it needs to — and under load, that’s the difference between coping and refusing connections:
SELECT ROUND(SUM(LENGTH(option_value))/1024/1024, 2) AS autoload_mb
FROM wp_options WHERE autoload = 'yes';
Under 1 MB is healthy. Over 3 MB is a problem you can fix today.
Consider whether you’ve outgrown the plan. Shared hosting has connection limits for a reason. A store doing real volume on a $10 plan will keep hitting this wall no matter how well the site is built.
Set up uptime monitoring. Intermittent database errors are invisible unless something is watching. Finding out from a monitor at 4 a.m. is better than finding out from a customer at 11.
If nothing here worked, it might not be the database
One thing worth ruling out: if the message you’re seeing changes — sometimes the database error, sometimes a blank page, sometimes a 500 — you may be chasing the wrong problem. A server under memory pressure produces different symptoms on different requests.
If you’re getting blank pages too, the white screen of death has its own diagnostic order, and it’s worth running through that one instead.
And if the database error appeared alongside anything else unusual — files you didn’t upload, an admin user you don’t recognise, redirects to sites you’ve never heard of — stop debugging and read what to do in the first hour after a hack. A filled disk and a corrupted table are also what a compromised site looks like from the outside.
The short version
Ask whether anything changed. If nothing did, skip wp-config.php entirely — the credentials are fine.
Check the admin for a different error message, check your host’s status page, and check your disk quota. If the error comes and goes, it’s connection limits, and that’s a conversation with your host.
Test the connection directly with a standalone script to separate WordPress from MySQL. Back up before you repair anything, and remove WP_ALLOW_REPAIR the moment you’re finished.
Most of the time this is a server-side capacity problem wearing a WordPress error message. Diagnosing it in that order takes about ten minutes. Starting with the credentials takes an afternoon and usually ends in the same place.
Site down right now?
We fix WordPress and WooCommerce emergencies — including the database problems that hosts and site owners tend to hand back and forth for hours. Get in touch: phone, email, or live chat, whichever is fastest.
Once you’re back up, our Maintenance Package is what keeps this from repeating: off-site backups, monitoring that catches intermittent failures before your customers do, and every update staged and tested first.
WPerizo.com — WordPress & WooCommerce. Nothing else. 🦔
