Troubleshooting · Explainer
What Causes "Error Establishing a Database Connection" in WordPress?
Short answer
The “Error Establishing a Database Connection” message means WordPress loaded but could not reach the database that holds its posts, pages, and settings. The usual causes are wrong login details in wp-config.php, a database server that is down or overloaded, a database that has hit its quota, or a damaged table.
Key takeaways
- WordPress stores posts, pages, and settings in a MySQL or MariaDB database, so a failed connection stops the whole site.
- The four details in wp-config.php are DB_NAME, DB_USER, DB_PASSWORD, and DB_HOST, and one wrong value is enough to cause the error.
- If every site on the same hosting account shows the same error, the database server is the likely cause, not one site.
- An error that comes and goes, often at busy times, points to an overloaded database server rather than a wrong setting.
- The debug log in wp-content/debug.log records the exact database error behind the plain message shown to visitors.
What does “Error Establishing a Database Connection” mean?
The message means WordPress started but could not open a connection to its database.
WordPress keeps posts, pages, users, and settings in a MySQL or MariaDB database, while its files hold themes, plugins, and uploads. When the database does not answer, WordPress has nothing to show, so it prints this one plain sentence instead of a page.
The message itself gives no detail about which part failed. WordPress.org's Common WordPress Errors page says the error means there is a problem with the connection to the database and lists several possible reasons, starting with wp-config.php.
WordPress.org's Requirements page recommends PHP 8.3 or greater and MySQL 8.4 or greater, or MariaDB 10.11 or greater, as of November 2026. A host running far older versions can still show this error when the database service stops or refuses connections. The WordPress minimum requirements guide lists the current versions to ask a host for.
What are the four main causes of this error?
Four causes cover almost every case: wrong login details, a stopped or overloaded server, a quota limit, or a damaged table.
WordPress.org's Common WordPress Errors page names wrong wp-config.php details first, then hosting problems such as a database that met its quota and shut down, or a server that is down. A hacked site is also listed as a later possibility once the first checks pass.
| Cause | First sign | Where to check |
|---|---|---|
| Wrong login details in wp-config.php | Error started after a move, a migration, or a password change | DB_NAME, DB_USER, DB_PASSWORD, DB_HOST in wp-config.php |
| Database server down | Every site on the account shows the same error | Host status page and hosting dashboard |
| Database quota reached | Site worked until a size or account limit was hit | Hosting panel database usage |
| Damaged table | wp-admin reports one or more tables are unavailable | wp-admin or the repair page |
The order matters: check the details first, then the server, then the tables. Guessing at tables before checking the login details wastes time when the fix is a single wrong password.
How do wrong wp-config.php details cause the error?
Wrong details cause the error because WordPress uses exactly four values from wp-config.php to log in to the database.
The file holds DB_NAME for the database name, DB_USER for the database username, DB_PASSWORD for the password, and DB_HOST for the database host. WordPress.org's Common WordPress Errors page lists all four and says to check them first.
Developer.WordPress.org's Editing wp-config.php page says wp-config.php sits in the root of the WordPress file directory and holds the base configuration details, including database connection information. A single typo in any of the four values breaks the login.
This cause is most likely after a site move, a host change, or a database password reset in the hosting panel. Full fix steps are in the guide to fix “Error Establishing a Database Connection”.
The password in wp-config.php must match the password the host has on file, so a reset in one place without updating the other breaks the site at once.
DB_HOST is the value people change least, yet it still causes failures. Many hosts use localhost, but some use a separate database server name, so a site moved to a host with a different setup needs the host value the new provider gives.
How can you tell if the database server is down?
You can tell by checking whether other sites on the same hosting account show the same error.
If a second site on the same account is also down with the same message, the database server is the likely cause, and no edit inside WordPress will fix it. If only one site is down, the fault is more likely in that site's wp-config.php or its own database.
WordPress.org's Common WordPress Errors page says to contact the host when the server is down or the database has met its quota and shut down. The host status page is the fastest place to confirm an outage.
A hosting dashboard that is slow or will not load at all is another sign of a server-side problem. When the panel itself struggles, the database server is often under the same load. MySQL's own documentation index lists the server manuals a host follows when it runs and repairs a MySQL server.
How can a corrupted database cause the error?
A damaged table can cause the error when WordPress cannot read the rows it needs to build a page.
Corruption is less common than wrong login details, and it usually shows a different clue: wp-admin reports that one or more tables are unavailable or need repair, while the front end shows the connection error. That split points at the tables rather than the login.
Developer.WordPress.org's Editing wp-config.php page documents a built-in repair option: adding define( 'WP_ALLOW_REPAIR', true ); to wp-config.php enables a repair page at /wp-admin/maint/repair.php. The same page warns that the setting should only be enabled when needed and disabled once the issue is solved.
The repair page works without a login while the setting is on, so the line must come out of wp-config.php as soon as the repair finishes. Leaving it in place leaves a maintenance page open to anyone who finds the address. The guide to fix corrupted database tables covers the repair steps in order.
What does it mean if the error comes and goes?
An error that comes and goes points to an overloaded database server, not a wrong setting.
Wrong login details fail every time, on every page load. A server that is short of connections or memory fails only when traffic peaks, then works again when the load drops, so the site may load fine in the morning and fail in the evening.
Shared hosting is where this pattern shows up most, because many sites share one database server. WordPress.org's Common WordPress Errors page notes that a connection timeout can happen when a site tries to do more than the server can manage, and it is common on shared hosting where the memory limit is restricted.
If the pattern matches busy times, ask the host whether the account hit a connection or resource limit. The guide on how to tell if your host is slowing WordPress down explains which host-side numbers to ask for before changing any setting.
How do you find the real error behind the message?
You find it in the debug log, because the public message hides the database error on purpose.
Developer.WordPress.org's Debugging in WordPress page shows the three lines to add above the “That's all, stop editing!” comment in wp-config.php: WP_DEBUG set to true, WP_DEBUG_LOG set to true, and WP_DEBUG_DISPLAY set to false. Errors are then written to wp-content/debug.log.
The same page says WP_DEBUG is false by default and is usually set to true in wp-config.php on development copies of WordPress. It also says WP_DEBUG_LOG needs WP_DEBUG enabled to do anything, and that the log is saved to debug.log in the content directory.
Load the broken page once, then open the log and look for the database error line. A refused connection points at the server or host value, while an access denied line points at the username or password.
Turn WP_DEBUG back to false when you are done, so error details stop being written to a file on a live site.
PHP's own manual lists core php.ini directives, including memory_limit with a 128M default as of November 2026. The guide to fix the WordPress white screen of death covers that separate case.
A low memory limit more often shows as a white screen or a memory error than as this message, so a memory line in the log points away from the database connection itself.
What mistakes should you avoid?
Do not edit wp-config.php without a backup copy of the file first.
A second typo made while fixing the first one can turn a small problem into a site that will not load at all. Download the file, keep the copy, and change one value at a time so you know which change fixed it.
Do not leave WP_ALLOW_REPAIR or WP_DEBUG switched on after the repair. Both settings open information or actions that should stay closed on a live site, and both are easy to forget once the site works again.
Do not reinstall WordPress as a first step. A fresh install does not fix wrong login details, a stopped server, or a quota limit, and it can overwrite files before you have a backup. Check the four login values, check the host status page, and only then look at tables.
Frequently asked questions
Does "Error Establishing a Database Connection" mean my content is gone?
No, in most cases your content is still in the database. The message means WordPress cannot reach the database right now, not that the data was deleted. Wrong login details, a stopped server, or a quota limit all block access while the rows stay in place. A backup made before the error is still the safest way to restore the site if a table turns out to be damaged.
Why does the error appear on the front end but wp-admin shows a different message?
The front end shows the short public message, while wp-admin can show more detail, such as a table that is unavailable. That split is a useful clue: it points at a damaged table rather than a failed login. Check wp-admin first when it loads, then follow the table repair steps instead of changing login details that may already be right.
Can a plugin cause a database connection error?
A plugin rarely causes this exact message, because the connection fails before most plugin code runs. A plugin can still trigger it indirectly by filling the database, running heavy queries that overload the server, or changing a setting that breaks the connection. If the error started right after a plugin change, the timing is worth noting, but check the login details and the server first.
How long does a database connection error usually take to fix?
A wrong password or host value can take minutes to fix once you find it. A stopped database server depends on the host, and can take from minutes to hours if the provider has an outage. A damaged table takes longer, because it needs a backup check, a repair run, and a check that the site loads cleanly afterwards.
Should I contact my host or fix it myself first?
Check the four login values in wp-config.php and the host status page first, since those two checks take minutes and rule out the most common causes. Contact the host when every site on the account is down, when the error comes and goes at busy times, or when the database has hit a quota. The host owns the server, so only the host can restart it or raise its limits.
Sources
- Common WordPress Errors WordPress.org
- Editing wp-config.php WordPress Developer Resources
- Debugging in WordPress WordPress Developer Resources
- Requirements WordPress.org
- Description of core php.ini directives PHP Manual
- MySQL Documentation MySQL
Is your product missing, or something out of date?
Tell us what to add or correct. We read every note and reply when we need a source. A message does not buy a ranking.
Thanks — we review requests within 3 business days.
