Fixing The Dreaded ‘Error Establishing a Database Connection’ in WordPress
- Last updated:
- 2 Comments
The longer you work with WordPress, the more likely you are to come across the dreaded ‘error establishing a database connection‘ message. This is a scary one, because you’ll likely be unable to access your site (or at least part of your site), and, if you haven’t yet gotten your head around a few fundamental concepts about servers and/or web development, you’ll probably be at a loss.
In this post, I’ll explain why this error is happening and share some steps you can take to fix it. If you’re in total freakout mode right now because it seems as though your entire site has disappeared, don’t worry — it’s incredibly unlikely your site is ‘gone’. Rather, it’s just having trouble accessing a key part of WordPress. Once you fix the connection, your site should 100% go back to normal.
So, take a deep breath. Now, let’s go through how to fix it.
What Does ‘Error Establishing a Database Connection’ Actually Mean?
There are two main parts to your WordPress website:
- Your site’s files — these are files such as the core WordPress software, your theme’s templates, plugin templates, and so on.
- Your site’s database — this is where your actual content and settings are saved.
For your site to work properly, its files need to be able to access the content and settings in your database. When a visitor lands on one of your blog posts, for example, WordPress:
- finds the database host
- connects to the database
- finds the WordPress posts table within that database
- looks up the content it’s trying to load.
In short, the infamous ‘error establishing a database connection‘ means WordPress can’t find this database. Your site is trying to access the database to look up the necessary content, but it can’t do that for some reason.
Why is this such a big issue? Well, in addition to the content of posts and pages, WordPress also stores a whole heap of other essential information in its database, such as its main settings, your user data, your selected theme, your widget settings, data for your active plugins, and so on. If WordPress can’t access any of the information within its database, it has no way of loading your website — that’s why you see the scary error message instead of your site.
What’s the Cause of a Database Connection Issue?
There are a number of issues that could cause a communication problem with your site’s database:
- Incorrect database credentials (username, password, host, database).
- Corrupted files.
- Corrupted database.
- The database server is overloaded or malfunctioning.
Over the next few sections, we’ll go into more detail about what these issues mean and how you can fix them.
But First — Back Up Your Site Before Troubleshooting Any Issues
While the troubleshooting steps you’ll be following aren’t dangerous, it’s always a good idea to have a backup — just in case. If you’re already using a tool such as Jetpack Backup — which we heartily recommend — you’re already backed up and good to go.
There are lots of plugins that can back up your site for you, but if you’re already locked out of WordPress you won’t be able to use them. In this case, you’ll need to use your cPanel or other hosting management software to make a complete backup.
If you don’t know how to do this, talk to your host — most quality web hosts will have a backup solution of sorts. Be sure to back up your database, as well as the files on your server, since it’s the database that contains all of the critical information for your website.
How to Troubleshoot/Fix the Error Establishing a Database Connection Message
Now, let’s dig into how to fix this error.
We’ve written the above list in order of likelihood, based on our experience, but you can start from the bottom and work up if you prefer. That said, if you don’t have a direct line (or chat support) with your host, it will be difficult to tell whether or not a database server is overloaded or malfunctioning on their end because from your end the symptoms are indistinguishable. In any case, let’s take a look at each of the causes and see what we can do to fix things.
1. Check for Incorrect Database Credentials
If you suddenly started seeing the error message on an existing site without making any changes, this is probably not the problem (you’ll probably be better served starting with the other troubleshooting tips). However, if you started seeing the error message after migrating WordPress or when setting up a new WordPress install, having incorrect database credentials is one of the most common causes of database connection issues.
To connect to your site’s database, WordPress needs four key pieces of information:
- Database name
- Database username
- Database password
- Database hostname
If you used an autoinstaller, the tool will automatically have filled in all of this information when you installed WordPress. However, issues will commonly arise when you migrate your site to a new host because the database credentials at your new host may not be the same as at your old host.
So, how can you find your database credentials to check if they’re correct or not?
You should be able to view your database credentials from inside your hosting dashboard. The exact location will vary depending on your host, but you’ll typically want to look for phrases such as ‘Databases’ or ‘MySQL Databases’. For example, in cPanel, opening the MySQL Databases tool will let you see all of your hosting account’s databases and database users.
And here’s another example of what it looks like in the custom dashboard used by Kinsta (a popular managed WordPress host):
Your best bet is to copy and paste all of the data directly from the medium in which it was given to you. (Note: Passwords can sometimes have dashes or periods at the end that aren’t normally selected.)
If you’ve recently switched hosts, make sure to double-check the ‘database host’ details. In most cases, this will be
localhost. However, some hosts may also use an IP Address or even a completely different URL, so it’s important to double-check. If you’re unsure about any part of this, you should either contact your host and ask them directly or look at their online knowledgebase (if they have one).
To re-enter these credentials into your WordPress site’s settings, you’ll need to connect to your WordPress site using an FTP client or your host’s file manager tool (if available). Then, download the
wp-config.php file, which should be located in your site’s root folder. Once you’ve downloaded it, edit it in any text editor — the database connection details are near the top and look something like this:
define('DB_NAME', 'database_name'); /** MySQL database username */ define('DB_USER', 'database_user'); /** MySQL database password */ define('DB_PASSWORD', 'database_password'); /** MySQL hostname */ define('DB_HOST', 'database_host');
Here’s an example of what it might look like in a real file:
The best way to ensure no errors is to copy and paste all of the database credentials directly from your hosting dashboard (making sure to avoid accidentally copying a trailing space or something similar). Once you’ve re-entered all of the credentials, re-upload the
wp-config.php file to your server and overwrite the existing one.
If, however, you’ve checked and double-checked all of these details, and you’re still getting the same error, then it’s time to move on to the next issue: Corrupted files.
2. Re-Upload Core WordPress Files to Check for Corrupted Files
In some cases, users have reported that re-uploading the core WordPress files sometimes fixes the error — the exact reason why this can work may seem like a mystery, but, in many cases, it has something to do with either resetting file permissions or replacing corrupt core files. (Note: Be sure not to overwrite either the
wp-config.php file, which contains crucial setup information, or the
wp-content directory, which holds your themes, plugins and media — and remember to always back up before modifying or replacing anything.)
To get this done, you’ll need to download a fresh version of WordPress from WordPress.org and unzip the package on your computer. Go into the unzipped folder, and delete both the
wp-config-sample.php file and the
wp-content folder to be sure you don’t accidentally replace the ones on your live server:
Once you’ve deleted them, follow these instructions:
- Open an FTP client and connect to your server.
- Upload all of the remaining files from the WordPress.org download.
- Tell your FTP program to overwrite all files.
Here’s what it looks like in FileZilla (a free, open-source FTP client). Your FTP client may look slightly different, but the basic terminology should be the same:
Once you’ve uploaded all of the files, you should be able to rule out any issues with corrupted files. If the error went away, great! If it didn’t, that means there probably wasn’t an issue with corrupted files and you may need to try another troubleshooting tip.
3. Repair Your Database to Check for Corrupted Database
A good indication of a corrupted database is if you can access the front end of your WordPress site but you see the error message when you try to access your WordPress dashboard (or vice-versa). You may also see an error message telling you some database tables can’t be found. Luckily, WordPress contains a tool that can help you to repair a corrupted database — all you need to do is enable it.
To do so, you’ll need to download your
wp-config.php file using FTP or a tool such as cPanel File Manager. You can find this file in the root directory of your WordPress install.
Once you’ve downloaded the file, open it with any text editor and add the following line above the ‘/* That’s all, stop editing! Happy publishing. */’ message:
define( 'WP_ALLOW_REPAIR', true );
Here’s an example of what it might look like:
Then, re-upload your
wp-config.php file and overwrite the existing one on your server. Once you’ve re-uploaded it, you should be able to access a special database repair page on your site by going to
yoursite.com with your actual domain). You should see a screen displaying two options:
- Repair Database.
- Repair and Optimize Database.
Click the Repair Database button to launch the database repair process.
Once WordPress finishes repairing your database, be sure to go back into
wp-config.php and remove the above-mentioned line of code from the file. The repair page isn’t hidden and isn’t secure; it will remain publicly accessible for as long as that piece of code exists in the config file.
I repeat: Make sure to remove the code snippet from your
wp-config.php file before calling it a day.
If your site still isn’t working, you can move on to the last troubleshooting tip.
4. Check to See If Your Database Server Is Overloaded or Malfunctioning
Malfunctioning and overloaded servers are very difficult to differentiate without either having access to advanced hosting tools or talking to your hosting company. If you suspect one of these is happening and your host has real-time telephone or chat support, then your best bet is to ask them what’s going on directly.
If you’re using a shared server (meaning you have to share the server’s resources with a large number of other people), it can be hard to tell whether the cause of the error is because of an overload or a malfunction. In some cases, instead of a malfunction, it may actually be because another site on the same server is overloading the database. In other words, even if you have only a very small site with no sudden surges in traffic, it could be experiencing an overload caused by someone else’s website. This is a lot less likely to happen with a VPS or a managed WordPress hosting setup.
The good news is both of these issues usually resolve themselves within a relatively short time. If a database physically malfunctions, your web host will almost always move to replace it as soon as their systems indicate the need to do so — and if a database goes down because of an overload, it will usually automatically reboot and be up and running again within a matter of minutes. However, if this has happened a number of times, alert your hosts and have them investigate as soon as possible.
If your website is on a shared server and your traffic is rapidly increasing, you may start to experience database connection issues as you start to overload the server. Such errors will usually resolve themselves, but will happen again if your website continues to experience surges in traffic. In such cases, if you aren’t already doing so, using a good caching plugin, such as W3 Total Cache, WP Super Cache or WP Rocket may well alleviate further issues.
That said, the easiest way to solve this issue is to prevent it from happening at all.
Still Frustrated? Use Managed WordPress Hosting to Prevent These Errors
While not a solution per se, moving over to a managed WordPress hosting provider could save you a lot of headaches if you’re already starting to see these types of errors. Managed WordPress hosting is less flexible from a features point of view, but, if all you need is to be able to run WordPress, it can be an excellent option. (This very site runs on such a service.) WordPress-specific managed hosting is tailored to running WordPress as efficiently and quickly as possible. The hardware, the server software, and the customer care representatives — just about everything, in fact — are geared towards (and optimized for) WordPress!
The downsides of this type of hosting are not being able to access your server via SSH, and not being able to install other scripts outside WordPress (i.e. you can run WordPress and nothing else). Additionally, most managed WordPress hosts will prohibit you from using certain plugins that have been deemed either substandard and/or unsuitable for their systems.
If you’re interested in managed WordPress hosting, take a look at the options. Some of the best are those offered by WP Engine (arguably the leader in the managed WordPress hosting arena), Kinsta (another solid option that’s priced similarly to WP Engine) and Flywheel (geared towards designers and agencies).
As you can see, the exact cause of the infamous WordPress ‘error establishing a database connection’ can be one of many. In our experience, however, in the vast majority of cases it’s either because of some kind of user-generated error (e.g. a typo in your
wp-config.php file) or is an issue that can be resolved by the user. If you’re having trouble, follow the methods outlined above to get your site up and running — and, if you’re still having no luck after that, talk to your host to have them look into the problem for you.
Finally, if you don’t want to have to deal with these types of errors in the future, your best bets are to either move to managed WordPress hosting or pay for a WordPress maintenance/support service. That way, you’ll have someone else monitoring your site and able to fix any errors that crop up.
If you’ve seen any edge cases or downright weird things happening in relation to this error, let us know in the comments below.