Error establishing a database connection: the full diagnostic sequence

TL;DR: This error means WordPress could not connect to the database. It does not tell you why, and the four underlying causes need completely different fixes: wrong credentials in wp-config.php, a database server that is down or unreachable, corrupted tables, or the connection limit being exhausted.

Diagnose before you change anything. A two-line PHP test file separates "credentials are wrong" from "the database server is not answering" in thirty seconds, and that single distinction eliminates half the possibilities. Editing wp-config.php at random, which is what most guides suggest first, frequently turns a temporary problem into a permanent one.

What the error actually means

WordPress stores all content, settings and user data in a MySQL or MariaDB database. On every page load it connects using the credentials in wp-config.php, queries what it needs, and renders the page.

When that connection fails, WordPress cannot render anything, so it shows this message instead. There is no partial degradation, because without the database there is nothing to display.

The message is deliberately generic and gives you nothing to work with. Behind it are four distinct situations:

The credentials are wrong, so the connection is refused. The database server is not running or not reachable. The database exists and connects, but tables are corrupted. Or the server is running and reachable, but has no available connections because they are all in use.

These have nothing in common except the symptom. Treating them as one problem is why people spend an hour editing wp-config.php when the actual cause is a database server that ran out of memory.

The other important framing: this error is frequently transient. If it appears intermittently — working, then failing, then working again — that pattern itself is diagnostic and points strongly at cause four rather than cause one.

First: is the site down or just the front end?

Two quick checks that shape everything after.

Try the admin area. Load /wp-admin. If you see a different message mentioning that one or more database tables are unavailable and suggesting repair, you have a corruption problem and can jump straight to cause three. If you see the same generic error, the connection itself is failing.

Check whether it is intermittent. Reload several times over a couple of minutes. A site that fails consistently points at credentials or a down server. A site that fails sometimes and works other times points strongly at connection exhaustion or resource limits, which is a completely different investigation.

Check your other sites if you host several on the same account or server. If all of them fail, the problem is server-level rather than site-level, and editing one site's configuration will not help.

Check whether anything changed. Did you just migrate, change hosts, update a plugin, edit wp-config.php, or change a database password in the hosting panel? A recent change is usually the cause, and reversing it is usually the fix.

Note the answers. They determine which of the four sections below is worth your time.

The two-minute test that narrows everything

This is the step most guides omit, and it is the most useful thing in this article.

Create a small PHP file in your site root that attempts a database connection using the same credentials as wp-config.php, then reports either success or the specific connection error. Use mysqli_connect with the host, username, password and database name, and echo mysqli_connect_error() on failure.

Then load that file in a browser.

If it connects successfully, your credentials are correct and the database server is up. The problem is elsewhere: corrupted tables, a wrong table prefix, a corrupted wp-config.php, or something in WordPress rather than the connection.

If it fails with an access-denied message, the credentials are wrong. Go to cause one.

If it fails with a connection-refused or host-unreachable message, the database server is not running or not reachable at that host. Go to cause two.

If it fails with a "too many connections" message, you have connection exhaustion. Go to cause four.

Thirty seconds of work, and you have eliminated three quarters of the possibility space. Delete the file afterwards, since a file echoing database errors is not something to leave on a public server.

Cause one: wrong credentials

wp-config.php holds four relevant constants: database name, user, password and host.

When this happens: immediately after a migration, after changing a database password in the hosting panel, after a host-side account change, or after someone edited the file.

Check each value against the hosting panel. Database names and usernames on shared hosting are usually prefixed with your account name, and a name that looks right may be missing the prefix.

Check the host value. localhost is correct on most shared hosting. Some hosts require an IP address, a specific hostname, or a port. If you migrated, the previous host's value will not work on the new one.

Check for whitespace and quoting. A trailing space inside the quotes, a smart quote introduced by a word processor, or a missing semicolon will break the file. If you edited wp-config.php in anything other than a plain text editor, this is a real possibility.

Check for special characters in the password. A password containing a quote character or a backslash needs escaping. The simplest fix is to reset the password to something long and alphanumeric.

Reset the password if in doubt. Change it in the hosting panel and update wp-config.php to match. This eliminates any question of a mismatch.

Check the user has privileges on that database. A user can exist and connect while having no rights to the specific database, which produces an access error that looks identical.

Always back up wp-config.php before editing, and edit in a plain text editor.

Cause two: the database server is down

The database service is not running, or not reachable from the web server.

On shared hosting, you generally cannot restart anything. Check your host's status page, then contact support. If multiple sites on the account are affected, this is almost certainly the cause and support is the only route.

On a VPS, check whether the service is running and start it if not. If it fails to start, the service log is where the reason lives.

The three most common reasons MySQL or MariaDB will not start on a small VPS:

Out of memory. The database was killed by the OOM killer, usually because the server has no swap and something spiked. This is extremely common on 1GB and 2GB instances. Adding a swap file, as covered in the new VPS checklist, converts a hard kill into temporary slowness.

Disk full. The database cannot write and refuses to start. Check free space. Logs, backups and Docker images are the usual culprits, and a full disk is one of the most common causes of sudden server failure precisely because it is so predictable and so rarely monitored.

Corrupted data files after an unclean shutdown. The log will say so, and recovery depends on the storage engine and the extent of the damage. This is where a tested backup stops being theoretical.

If the service starts and then dies again shortly afterwards, it is almost always memory or disk, not configuration.

Cause three: corrupted tables

The connection works but one or more tables are unreadable.

The signal: loading /wp-admin gives a message about one or more database tables being unavailable and suggesting repair, rather than the generic connection error.

Back up first. Take a copy of the database before attempting repair, because repair operations can occasionally make things worse and you want the option to try something else.

Enable WordPress repair mode. Add define('WP_ALLOW_REPAIR', true); to wp-config.php, then visit /wp-admin/maint/repair.php. This offers repair, and repair with optimisation. Run repair first.

Remove the constant immediately afterwards. The repair page is accessible without authentication by design, so leaving it enabled means anyone can run database operations on your site.

If WordPress repair does not resolve it, use mysqlcheck from the command line or the repair function in phpMyAdmin, which operate at a lower level.

If repair fails entirely, restore from backup. Corruption beyond automated repair is where your backup strategy is the whole answer, and where an untested backup becomes an expensive lesson.

Find out why it corrupted. Repair without root cause means it recurs. The usual reasons are unclean shutdowns from crashes or power loss, disk problems, running out of disk space mid-write, or using MyISAM tables, which corrupt far more readily than InnoDB. Converting MyISAM tables to InnoDB is worthwhile if you find any.

Cause	Diagnostic signal	Typical trigger	Fix
Wrong credentials	Test file: access denied	Migration, password change, file edit	Correct wp-config.php values
Wrong DB host	Test file: unknown host	Migration to new host	Use the host's documented value
Server down: memory	Service fails to start, OOM in log	No swap, memory spike	Add swap, increase RAM
Server down: disk full	Service fails to start, no space	Logs, backups accumulating	Free space, add monitoring
Corrupted tables	Admin suggests repair	Unclean shutdown, MyISAM	Repair, then restore if needed
Connection limit	Test file: too many connections	Traffic spike, no persistent limits	Reduce concurrency, raise limit
Wrong table prefix	Connects, but WordPress fails	Migration, manual DB work	Match prefix in wp-config.php
Corrupted config file	White screen or parse error	Editing in a word processor	Restore from backup

Cause four: connection limit exhausted

The intermittent case, and the one people misdiagnose most often.

Database servers permit a finite number of simultaneous connections. When they are all in use, new connection attempts fail, and WordPress shows the connection error. Moments later, when connections free up, the site works again.

The signal: intermittent failures, often correlating with traffic peaks, and the test file reporting too many connections.

On shared hosting, your connection allowance is set by the host and is shared with your own other sites. Common causes are a plugin opening connections without closing them, a traffic spike, or another of your sites consuming the pool.

Common contributors:

A traffic spike, particularly on pages that cannot be cached. This is the same mechanism that breaks stores during sales, covered in the festival sale preparation guide.

Missing or broken page caching, so every visitor triggers database queries that a cache should have absorbed.

Slow queries holding connections open longer than necessary, which reduces effective capacity even when the limit is untouched.

A plugin with a connection leak.

Backup or scan jobs running during peak hours.

Bot traffic hitting uncacheable URLs such as search results.

The fixes, in order of value: get full-page caching working properly, since that removes most database load outright. Add object caching so repeated queries resolve from memory. Find and fix slow queries. Move scheduled jobs off peak. Block abusive bot traffic. And only then consider raising the connection limit, which on a VPS is a configuration change and on shared hosting is a support request.

Raising the limit without addressing the cause usually just moves the failure point.

Preventing recurrence

Most of these are avoidable with a few controls.

Monitor disk space with an alert at 80%. Full disks cause database failures and are entirely predictable.

Add swap on a VPS. Without it, a memory spike kills the database rather than slowing it down.

Get caching working and verify it. Not installed, verified — check response headers for a cache hit. Most connection exhaustion is really a caching failure.

Add object caching on dynamic sites and stores, which is where page caching does not reach.

Use InnoDB, not MyISAM. InnoDB is crash-safe and corrupts far less readily. Check whether any legacy tables are still MyISAM and convert them.

Move scheduled jobs off peak. Backups and security scans at midday are a recurring cause of resource problems.

Keep a copy of wp-config.php somewhere safe, so a bad edit is a thirty-second recovery rather than a reconstruction.

Test backup restores quarterly. Table corruption beyond repair is exactly the scenario where an untested backup fails you.

Monitor from outside the server. An uptime check catches this within minutes rather than whenever someone happens to visit.

FAQs

What causes error establishing a database connection in WordPress?

Four distinct things: incorrect credentials in wp-config.php, a database server that is down or unreachable, corrupted database tables, or the connection limit being exhausted. They share a symptom and nothing else, so diagnosis matters before you change anything.

How do I know which cause I have?

Create a small PHP file that attempts a connection with the same credentials and reports the specific error. Access denied means wrong credentials, connection refused means the server is down, and too many connections means exhaustion. If it connects successfully, the problem is corrupted tables or a wrong table prefix rather than the connection itself.

Where are WordPress database credentials stored?

In wp-config.php in your site root, as four constants for database name, username, password and host. Check each against your hosting panel, remembering that shared hosting usually prefixes database names and usernames with your account name, and that the host value is often localhost but varies by provider.

Why does the error appear only sometimes?

Intermittent failure points strongly at connection exhaustion rather than credentials, since wrong credentials fail consistently. The database has a finite connection limit, and when traffic peaks exhaust it, new connections fail until others close. The underlying cause is usually missing or broken page caching.

How do I repair corrupted WordPress database tables?

Back up the database first, then add define('WP_ALLOW_REPAIR', true); to wp-config.php and visit /wp-admin/maint/repair.php. Remove that constant immediately afterwards, since the repair page is accessible without authentication. If WordPress repair fails, try mysqlcheck or phpMyAdmin, and restore from backup if repair cannot recover the tables.

What database host should I use in wp-config.php?

localhost on most shared hosting, but some providers require a specific hostname, an IP address, or a port. Check your host's documentation, and note that a value carried over from a previous host after migration will not work. The connection test file will report an unknown host if this is your problem.

Why did this start after I migrated my site?

Because the database credentials, database host value, or table prefix from the old server do not match the new one. Migration is the single most common trigger for this error. Check all four wp-config.php values against the new host's panel, and confirm the table prefix matches what was actually imported.

Can a plugin cause this error?

Yes, in two ways. A plugin with a connection leak can exhaust the available connections, producing intermittent failures. A plugin running heavy unindexed queries can hold connections open long enough to reduce effective capacity. Both present as intermittent rather than constant failure.

What if my database server will not start on a VPS?

Check the service log, which names the reason. The three most common are running out of memory, where adding swap prevents recurrence; a full disk, where the database cannot write; and corrupted data files after an unclean shutdown. If the service starts then dies shortly after, it is nearly always memory or disk.

Should I just raise my database connection limit?

Only after addressing the cause, since raising it without fixing the underlying load usually moves the failure point rather than removing it. Get full-page caching verified and working, add object caching, fix slow queries and move scheduled jobs off peak first. Then raise the limit if it is still genuinely the constraint.

Is MyISAM or InnoDB better for WordPress?

InnoDB, which is crash-safe, handles concurrency properly and corrupts far less readily than MyISAM. If a repair operation reveals MyISAM tables on an older site, converting them to InnoDB is worthwhile and reduces the chance of recurrence.

How do I prevent this error from happening again?

Monitor disk space with an alert at 80%, add swap on a VPS so a memory spike does not kill the database, verify page caching is actually caching, add object caching on dynamic sites, convert any MyISAM tables to InnoDB, move backups and scans off peak hours, and test a backup restore quarterly.

Conclusion

The message tells you what failed and nothing about why, and the four causes behind it need entirely different responses.

So resist the reflex to start editing wp-config.php. Run the connection test file first. Thirty seconds of work tells you whether the credentials are wrong, the server is down, or the connections are exhausted, and that single distinction saves you from an hour of changing values that were already correct.

Two patterns are worth recognising immediately. Intermittent failure is almost never a credentials problem, because wrong credentials fail every time; it is connection exhaustion, and the real fix is usually caching. And an admin area suggesting table repair is corruption, which is a different path entirely.

If you have just migrated, check the database host value. It is the one people carry over from the old server without thinking, and it is wrong more often than the password.

Prevention is mostly unglamorous: disk alerts, swap on a VPS, caching that you have verified rather than assumed, InnoDB rather than MyISAM, and a restore you have actually tested. The last one matters most, because corruption beyond repair is the case where nothing else helps.

HostCloud runs WordPress on NVMe with managed MySQL, server-level caching and automated daily backups restorable from the panel, with support that can check the database service directly rather than asking you to. Plans from ₹99 a month at https://hostcloud.in.