You load your website and the whole page is gone. In its place sits one grey line of text. It reads “Error establishing a database connection” and nothing else. No menu, no logo, no content, and no dashboard. For most owners this is the scariest WordPress message of all.<\/p>\n
The message is actually quite precise. WordPress stores every post, page, user and setting in a database. On each visit it opens a connection to that database and asks for the content. When that connection fails, WordPress cannot build a single page. So it stops and prints this one line instead.<\/p>\n
The impact is instant and total. Your shop stops taking orders. Your contact forms stop working. Search engines that crawl during the outage see a broken site. You usually cannot log in either. The login screen needs the database too. Every minute of downtime costs you traffic and trust.<\/p>\n
The good news is that the list of causes is short. Wrong details in one wp-config file cause most cases. A database server that is down, suspended or out of space causes many more. Damaged tables, a changed password, a bad site move or a hack explain the rest. This guide covers the signs and the causes. It then gives a safe step-by-step fix and the habits that prevent a repeat.<\/p>\n
This error has a clear fingerprint. Reading the signs first tells you which cause to chase. It also separates the problem from other WordPress outages.<\/p>\n
The clearest sign is the wording itself. You see plain text that says “Error establishing a database connection”. There is no styling at all. Your theme lives in the database too. The page usually returns an HTTP 500 status underneath. That is unlike a plain 500 internal server error<\/a>, which tells you nothing.<\/p>\n The second sign is how complete the failure is. Every page fails, not just one. The home page, blog posts, shop pages and login screen all show the same line. If only some pages fail, the database is almost certainly fine. In that case you are looking at a theme, plugin or permalink problem instead.<\/p>\n A third sign appears in the dashboard area. Visit your admin address and watch the exact wording. It may say “One or more database tables are unavailable. The database may need to be repaired”. That means the connection works but tables are damaged. That version of the message points you straight at Step 7. If the dashboard shows the same connection error, the database is unreachable altogether.<\/p>\n A fourth sign is the timing. Note what changed in the hour before the outage. A host move, a plugin update or a password change in your panel are strong clues. So is a sudden traffic spike. An error that comes and goes every few minutes suggests a connection or resource limit. An error that is constant suggests wrong login details or a stopped database service.<\/p>\n A fifth sign comes from turning on debugging. Add Each cause below breaks the connection at a different point. Knowing which point failed tells you which step to use.<\/p>\n WordPress keeps your database details in a file called wp-config.php. It reads the database name, the user name and the password from there. It then logs in to the database server using those three values. If any one of them is wrong, the server refuses the login. WordPress has no fallback, so it prints the connection error. This is the most common cause by far. It usually follows a manual edit or a site move.<\/p>\n The wp-config file also holds a database host value. On many servers that value is simply localhost. Other hosts run the database on a separate machine with its own name. Some setups need a numeric address or a specific port. If the host value points nowhere useful, the connection times out. The symptom looks just like a wrong password. That is why people chase the wrong fix.<\/p>\n Your database runs as a service alongside your web server. That service can crash or be stopped for maintenance. A server reboot can also leave it switched off. While it is down, nothing can connect to it at all. Your files are untouched, but every page still fails. This cause is common on self-managed servers and small virtual machines.<\/p>\n Hosting accounts come with hard limits. There is a cap on database connections at once. There is often a storage quota for the database itself. The disk itself can also fill up. The WordPress docs list a database that has met its quota and been shut down as a known cause. When a limit is hit, new connections are refused until load drops. That is why the error can flicker on and off during busy periods.<\/p>\n The database user is separate from your WordPress login. Someone may reset its password in the hosting panel. A host may rebuild the account during a plan change or migration. A user can also keep its password but lose its grants on the database. In every case the login succeeds or fails at the server, not in WordPress. The result on screen is the same single line of text.<\/p>\n A sudden shutdown or a full disk can damage a table. A failed plugin update can leave a table half written. Once a table header is damaged, the database cannot read it. WordPress can still connect, but it cannot fetch what it needs. The message then changes to say tables are unavailable and may need repair. This version of the fault is narrower and easier to fix.<\/p>\n WordPress runs its database queries through its own core files. Those files live in the wp-includes and wp-admin folders. A failed update or a bad upload can leave one of them truncated. Malware can also modify core files on purpose. If the database layer itself is damaged, no connection can be made. The error then appears even though your login details are perfect.<\/p>\n Attackers often target wp-config.php. It holds your login details. An attacker may change the host value or inject code above it. Stray characters or whitespace before the opening PHP tag break the file. The WordPress docs list a hacked site as a cause to check. Rule out login details and hosting first. A hacked site can also drop or rename tables. Treat this cause seriously rather than as an afterthought.<\/p>\n Moving a site touches the database twice. You export it from the old host and import it to the new one. The import can finish with a different database name than expected. The table prefix can also differ between the two copies. WordPress then connects, but finds no tables it knows. Sometimes the import never finished. The database is then simply empty.<\/p>\n Follow these steps in order. They move from simple checks to deeper repairs. Several steps edit files or data that can break a live site. Make a backup before you begin. If you cannot reach the dashboard, ask your host for a snapshot. You can also copy the files and database by hand over SFTP.<\/p>\n This step addresses a wrong database name, user or password. WordPress reads those three values from one file and uses them to log in. A single wrong character makes the database server refuse the connection. Because there is no fallback, every page fails at once.<\/p>\n Confirm the cause by comparing the file with your hosting panel. Connect over SFTP and download wp-config.php from your site root. Open it in a plain text editor and find the lines for DB_NAME, DB_USER and DB_PASSWORD. Then open your hosting panel. List the databases and database users for your account. A healthy result is three exact matches. Watch capital letters and any account prefix.<\/p>\n Editing this file can take your site offline. Download a copy before you change it. Correct any value that does not match. Leave the quotation marks in place. Watch for a password with a dollar sign or a backslash. Those characters need care inside double quotes. Use single quotes around the value if you are unsure. Save the file and upload it back to the same location.<\/p>\n Verify by loading your home page in a private browser window. A correct set of details brings the site straight back. If the error stays, look for stray spaces before the opening PHP tag. If every value matches your panel exactly, move on to Step 2.<\/p>\n This step addresses a wrong database host value. WordPress needs to know which machine answers database requests. Many servers use localhost, but plenty of hosts use a dedicated server name. If the value points at the wrong machine, the connection simply times out.<\/p>\n Confirm the cause by finding the correct value in your hosting panel. Open the database details screen. It normally lists the host name next to the database. Shared hosts often publish it in their knowledge base too. Compare it with the DB_HOST line in your wp-config file. A healthy value matches the panel exactly. Include any port after a colon.<\/p>\n Take a fresh copy of the file before editing it again. Replace the DB_HOST value with the one from your panel. If localhost fails, try 127.0.0.1. Some stacks only accept the numeric form. If your host gives you a socket path, use the form they document. Save and upload the file.<\/p>\n Verify by reloading the site and watching how long it takes to fail. A wrong host usually hangs for several seconds before erroring. A correct host either loads the site or fails at once. An instant refusal means the host is right. The login details are wrong, so return to Step 1. If the site still hangs, continue to Step 3.<\/p>\n This step tells you whether the database server is running at all. It separates a dead service from bad login details. That distinction decides whether you fix WordPress or call your host. It is the fastest way to stop guessing.<\/p>\n Confirm the cause with a short test script. Create a file named dbtest.php in your site root with this content: Act on the message you get. A line about access denied means the login details are wrong. Go back to Step 1. A refused or timed-out connection means the service cannot be reached. Contact your host and quote the exact message you saw. Delete dbtest.php as soon as you are finished. It holds your database password in plain text.<\/p>\n Verify by reloading your site after your host restarts the service. The site should return without any further change on your side. If your host confirms the service is healthy, the limit may be the issue. Move on to Step 4.<\/p>\n This step addresses a connection, storage or disk limit. Hosting accounts cap how many database connections may run at once. They also cap how large the database may grow. When a cap is reached, the server refuses new connections until load falls.<\/p>\n Confirm the cause by looking at your resource usage screen. Most panels show current and peak connections. They also show database size against quota. Check free disk space on the account as well. A healthy result shows peaks well below each limit. You should also see free space. Did a peak touch the cap in the same minute the site failed? That is your answer.<\/p>\n Reduce the load rather than raising limits blindly. Clear large transient rows and old post revisions. Both often bloat a database. Switch off any plugin that writes a lot, such as a stats or log plugin. Enable page caching so most visits never touch the database. If the peaks are real, ask your host to raise the limit. A larger plan may be the answer.<\/p>\n Verify by watching the usage graph for an hour after the change. Connections should stay comfortably below the cap. Load the site repeatedly and confirm it no longer flickers. If your usage was always low, limits were not the cause. Continue to Step 5.<\/p>\n This step addresses a database user that lost its password or privileges. The database user is separate from your WordPress account. A panel reset or a plan change can silently alter it. The server then refuses the login even though your file looks correct.<\/p>\n Confirm the cause from the test in Step 3. An access denied message names the user that was refused. Open your hosting panel and find that user under database users. Check that it is still assigned to your database. A healthy setup shows the user attached to the database with all privileges granted.<\/p>\n Reset the password and keep both copies in step. Changing the password breaks your site until the file is updated. So do both edits in one sitting. Create a new password in the panel. Avoid odd characters that need escaping. Assign the user to your database again and grant all privileges. Then put the same value in DB_PASSWORD in wp-config.php. Upload the file.<\/p>\n Verify by running your test script once more before loading the site. It should print Connected straight away. Then load the home page and the dashboard. Remember to delete the test file again. If the connection works but pages still fail, move to Step 6.<\/p>\n This step addresses a migration that left the wrong database behind. WordPress can connect perfectly and still find nothing to read. That happens when the import went to a different database or used a different table prefix. The result on screen looks like a connection failure.<\/p>\n Confirm the cause inside phpMyAdmin or your panel’s database tool. Open the database named in your wp-config file. Look for the core tables, such as options and posts. Note the characters in front of their names. That is your table prefix. A healthy database holds about a dozen core tables. They all share one prefix.<\/p>\n Line the two halves up again, carefully. Importing data can overwrite a working site. Export the current database first. Keep that file somewhere safe. If the database is empty, import your backup into it now. Does the prefix differ from the one in your wp-config file? Change the Verify by loading the site and then the dashboard. Your posts, pages and settings should all return. Check a few internal links and a shop page if you run one. If tables exist but some will not open, you are facing damage rather than a mismatch. Go to Step 7.<\/p>\n This step addresses corrupted database tables. A crash, a full disk or an interrupted update can damage a table. WordPress still connects but cannot read the damaged table. The message then says one or more tables are unavailable and may need repair.<\/p>\n Confirm the cause by reading the wording at your dashboard address. The repair wording is a clear signal. The plain connection wording is not. You can also open phpMyAdmin and check each table’s status. A table marked in use is suspect. So is an odd row count. A healthy table opens and browses without a warning.<\/p>\n Repairs change data. Export a full copy of the database before you touch anything. WordPress has a built-in repair tool you can switch on. Add Verify by loading your dashboard and a few front-end pages. The repair screen also lists the tables it fixed. Check that your recent posts and orders are still there. If repair reports success but the error returns later, raise it with your host. Your disk or database may be failing. If repair cannot help at all, continue to Step 8.<\/p>\n This step addresses corrupted or missing core files. WordPress runs every query through code in wp-includes and wp-admin. A failed update can leave one of those files cut short. If the database layer itself is damaged, no connection is possible.<\/p>\n Look for other signs of a broken update. A site stuck after an update often also shows maintenance mode<\/a> or a blank admin page<\/a>. Compare the file sizes in wp-includes with a fresh download from WordPress.org. A zero-byte or oddly small file is a strong clue. Your error log may also name a missing file.<\/p>\n Replace the files carefully, keeping your own content untouched. Back up the whole site first. Overwriting files cannot be undone. Download the matching WordPress version from WordPress.org. Unzip it on your computer. Upload only the wp-includes and wp-admin folders. Let them overwrite what is there. Never upload the wp-content folder or wp-config.php. They hold your themes, uploads and login details.<\/p>\n Verify by loading the home page and then the dashboard. WordPress may ask you to run a database update. That is normal after a file refresh. Our guide to the database update required message<\/a> covers that screen. If the error survives a clean core, treat the site as hacked. Go to Step 9.<\/p>\n This step addresses a hacked site with an altered wp-config file. Attackers target wp-config.php because it holds your login details. They may change the host value or inject code. They may drop tables outright. The WordPress docs list a compromised site as a cause to check once login details and hosting are clear.<\/p>\n Confirm the cause by reading the file and the logs. Open wp-config.php and look for anything above the opening PHP tag. Look for odd functions, long encoded strings, or remote file calls. Check your access log for repeated login attempts near the time of the outage. Then run a malware scan. Use a trusted security plugin or your host’s scanner.<\/p>\n Clean up in the right order. A rushed restore can reinfect the site. Take a forensic copy of the current files and database before you change anything. Change every password. That means hosting, SFTP, the database user and every admin. Restore files and database from a backup taken before the first sign of trouble. Then update WordPress, every plugin and every theme. Remove anything you do not know.<\/p>\n Verify by loading the site and rescanning it afterwards. Check that the admin list holds only people you know. Watch the error and access logs for a few days. If you have no clean backup, ask your host for an older snapshot. Professional help is wise at this point. A partial clean-up usually fails.<\/p>\n Each habit below closes off one of the causes above. None of them takes long once set up.<\/p>\n Protect your wp-config file and your login details. Keep a safe note of the database name, user, host and password. Never edit wp-config.php on a live site without saving a copy first. Give the database user only the rights it needs. Change the password when a contractor’s access ends. Update the file in the same sitting.<\/p>\n Keep your database small and tidy. Limit stored post revisions with a setting in your wp-config file. Clear expired transients and old session rows on a set schedule. Remove plugins that log every page view unless you need the data. A lean database stays inside your storage quota. It also recovers faster from a repair.<\/p>\n Watch your resource usage before it bites. Check the connection and storage graphs in your panel each month. Set an alert if your host offers one. Add page caching so most visitors never reach the database. Plan your upgrade before a busy season, not during one. That also helps you avoid a 503 service unavailable error<\/a>.<\/p>\n Test every change somewhere safe. Build a staging copy. Run updates and site moves there first. Check the table prefix and database name before you point live traffic at a new host. Keep the old host live for a few days after a move. That overlap gives you a fallback if the import was short.<\/p>\n Back up properly and prove that restores work. Schedule daily backups of files and database. Store the copies off the server. Use a tool such as UpdraftPlus<\/a>. Keep at least two weeks of history. Restore a backup to a staging site once a quarter. Treat it as a drill. Keep WordPress, plugins, themes and PHP updated. That lowers the chance of a hack. Add uptime monitoring. Then you hear about an outage before your customers do.<\/p>\n The error establishing a database connection message is alarming but narrow. It means WordPress could not reach the place your content lives. The whole site fails together. Every page needs that connection. The plain grey page is a symptom, not a mystery.<\/p>\n The signs tell you a great deal. Total failure across every page points at the connection itself. Wording about tables needing repair points at damage instead. A fault that flickers points at a resource limit. A constant fault points at login details. Debug logging usually names the refusal outright.<\/p>\n The causes are a manageable list. Wrong login details or a wrong host value. A stopped database service, or a limit that has been reached. A changed database user, damaged tables or damaged core files. A hack, or a migration that left the wrong database behind.<\/p>\n The fix follows the same order every time. Check your login details and host value. Then test the connection with a small script. Review your hosting limits. Reset the database user, then check your tables and prefix. Only then repair tables, replace core files, or treat the site as hacked. Back up before each step that edits files or data.<\/p>\n Prevention comes down to tidy habits. Guard your login details and keep the database lean. Watch your usage and test changes on staging. Back up daily and rehearse a restore. If a bare 400 message appears instead of this one, read our guide on how to fix the 400 Bad Request error in WordPress<\/a>. For the official reference, see the WordPress common errors handbook<\/a> and the wp-config.php docs<\/a>.<\/p>\n","protected":false},"excerpt":{"rendered":" Introduction You load your website and the whole page is gone. In its place sits […]<\/p>\n","protected":false},"author":1,"featured_media":4346,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[10],"tags":[531,532,389,343,533],"class_list":["post-4341","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-wordpress","tag-database-connection-error","tag-wordpress-database","tag-wordpress-errors","tag-wordpress-troubleshooting","tag-wp-config-php"],"yoast_head":"\ndefine( 'WP_DEBUG', true );<\/code> and define( 'WP_DEBUG_LOG', true );<\/code> to your wp-config file. WordPress then writes database errors to a log file inside your content folder. The log often names the exact refusal, such as access denied for a user. That one line can save you an hour of guesswork.<\/p>\nReasons Why Error Establishing a Database Connection Happens<\/h2>\n
Wrong Database Name, User or Password<\/h3>\n
The Wrong Database Host Value<\/h3>\n
The Database Server Is Down or Not Running<\/h3>\n
A Connection, Storage or Disk Limit Has Been Reached<\/h3>\n
The Database User Lost Its Password or Privileges<\/h3>\n
Corrupted Database Tables<\/h3>\n
Corrupted or Missing WordPress Core Files<\/h3>\n
A Hacked Site With an Altered Configuration File<\/h3>\n
A Migration Left the Wrong Database Behind<\/h3>\n
How to Fix Error Establishing a Database Connection in WordPress (Step by Step)<\/h2>\n
Step 1: Check Your Database Details in wp-config.php<\/h3>\n
Step 2: Confirm the Database Host Value Is Right<\/h3>\n
Step 3: Test the Connection With a Small PHP File<\/h3>\n
<?php $c = new mysqli('DB_HOST','DB_USER','DB_PASSWORD','DB_NAME'); echo $c->connect_error ?: 'Connected'; ?><\/code>. Replace the four placeholders with the values from your wp-config file. Open the file in your browser and read the result. The word Connected means the service is alive and your details work.<\/p>\nStep 4: Check Your Hosting Limits for Connections, Quota and Disk Space<\/h3>\n
Step 5: Reset the Database User Password and Check Its Privileges<\/h3>\n
Step 6: Confirm the Database Holds Your Tables and the Prefix Matches<\/h3>\n
$table_prefix<\/code> line to match the tables. Do not rename tables when changing one line will do.<\/p>\nStep 7: Repair Corrupted Database Tables<\/h3>\n
define( 'WP_ALLOW_REPAIR', true );<\/code> to wp-config.php. Then visit your site address followed by \/wp-admin\/maint\/repair.php and run the repair. The official docs warn that this page needs no login while enabled, so remove the line the moment you are finished. If the tool cannot fix a table, select it in phpMyAdmin. Use the repair table option there.<\/p>\nStep 8: Replace the WordPress Core Files<\/h3>\n
Step 9: Check for a Hack and Restore a Clean Backup<\/h3>\n
Best Practices to Prevent Error Establishing a Database Connection in Future<\/h2>\n
Conclusion<\/h2>\n