Fixing the WordPress “Establishing a Database Connection” Error

One of the most infuriating things about dealing with software, coding, and development is error messages. Almost no one in the history of the world has been able to write a part of software with graceful failure states and verbose error messages that tell you what the problem is.

There’s a reason for this, of course. The average user doesn’t know enough to fix whatever an error is. If an error message gives information they’re more likely to misconstrue it or ignore it. Some will even try to fix it and, in their ignorance, break more than they fix. Developers who know what they’re doing can look for more information in log files and error codes, to take a generic error and turn it into a set of steps to fix an underlying problem.

The stereotypical Windows blue screen of death was always one of these errors. To most users, a blue screen is a blue screen. To those well-educated, the hex error code seems like a useful lead. Even still, the pointer could be inaccurate. Here’s an example: I had a PC where the processor was going bad, and each time the processor errored, the computer blue screened and the blue screen hex code pointed at whatever was in use by the processor at that exact second. Essentially, the processor threw up its hands and went “it wasn’t me, it was… THEM!” randomly every time - it took a long time to diagnose the underlying cause, like replacing other parts that were perfectly fine.

All of this is basically a digression to say that some error codes are easier than others to diagnose. On one end, you have nice, descriptive error codes. On the other end, you have errors like the blue screen. Unfortunately, the WordPress “Error Establishing a Database Connection” is one of the latter. There are a number of different possible causes, and there’s no way to tell which is which without going through them and testing to see if a given answer resolves the issue. The good news is that in most cases, this error can be resolved in under 30 minutes if you know where to look.

So, let’s go through the possible causes and see if we can help you figure out what’s wrong with your instance.

Behind the Error

The first step to understanding any error is knowing what caused it. In the case of the database connection error - one of Sherlock Holmes’s least interesting stories - it helps to understand how WordPress works and how this error can appear.

WordPress is a framework that uses PHP and MySQL to create a website. PHP - a programming language - is used in template files to pull elements of data from a database or generate other elements on its own. The database it pulls data from is set up in MySQL, which by default listens on port 3306.

Your database sits on your server and holds your website content and static elements. Everything from your blog post content to your site title to your color settings are stored in the database. You can see your database settings in your wp-config.php file.

When a user visits your site, your server gives them the PHP files they need to render your site. Those PHP files, while rendering the page, need to connect to the database to get data necessary for rendering the site. If, for some reason they can’t connect to your database, you get the Error Establishing a Database Connection - it’s worth mentioning that if you’re on a host that caches your site - Kinsta, just to give you an example, caches WordPress sites for one hour by default - some visitors might not immediately see the error, which can make it harder to gauge how widespread the problem is.

This has a few implications. One of them is actually quite reassuring. The error is in creating a connection to the database - not in the database itself. Usually this error means a configuration issue or a code conflict, and not an error with the site’s data itself. You don’t usually have to worry about your site’s content disappearing.

In most cases, that means that your database credentials are incorrect, or that you haven’t given your database user full permissions to access your database in your cPanel.

Of course, if your database is deleted, you won’t be able to connect to it and this error will pop up; it’s a worst-case scenario so don’t worry too much about it. Chances are your problem comes from somewhere else in the chain. Let’s look at those possible causes.

Hosting Issues

There are three kinds of problems that could come up with your web host that cause the error connecting to your database.

The first is actual downtime with your web host. Many web hosts promise 99.999% uptime, to a number of digits out. But 99 is not 100. Even the best web host can have a catastrophic issue and go down. Maybe it’s an entire data center, or maybe it’s just a problem with the single server hosting your website. If you’re on shared hosting - which smaller sites often are, because it’s cheaper - another customer on the same server could be hogging the bandwidth or server resources and crowding out your site. As a general rule, you want your server’s CPU, RAM and disk usage to remain below 80% for optimal performance; if any of these are maxed out, it can prevent WordPress from creating a database connection.

It’s worthwhile to check with your web provider to see if they see any errors. They can tell you if the problem is on their end and they can sometimes help you troubleshoot through a few other common causes. Figure out where your web host support is and see if you can set up a live chat or an email/phone support ticket. Live chat is the best, as you can work directly with a support agent without needing to relay instructions tediously over voice.

If the web host is having issues they can probably solve the problem pretty quickly, depending on the scale of the problem. In either case, what you’re looking for is to confirm whether or not the error is on their end. There’s nothing worse than troubleshooting a problem for hours just to find it wasn’t something you could fix.

I said there are three kinds of issue with web hosting. But I’ve only talked about one. The other two are variations of a DDoS.

A DDoS attack is fairly easy to understand. Imagine any business with a handful of doors at the front to let people in and out. Now think of Black Friday, and how crowds make it slow to get in or out of the building. If the store is your web server and the customers are your visitors, that’s the basis of a DDoS attack. Too many people trying to use too limited resources to access your site.

A bad DDoS attack means an outside agent uses a botnet to create thousands of artificial requests to clog the doorways. A “friendly” DDoS attack is when your site goes viral and gets 100x its normal traffic, which makes it impossible to access the site because too many people are trying to access it at once. Reddit calls this the “hug of death” - it’s a “good” problem to have, in that you like going viral and you like the traffic and interest. But if it takes down your site, it’s still a problem.

On shared hosting, someone else on your web server could be the target of a DDoS attack of either sort and it’s bringing down your site from the collateral damage. The other stores are crowded out because they’re in the mall too.

A DDoS isn’t something you can just stop or fix. But you can take some steps to make your site harder to take down - it’s a bit involved, so I’m not going into it here. But you can read up on it elsewhere.

Authentication Issues

Once you have eliminated hosting problems as possible causes, you can look at problems you might have caused. Here are a few possibilities.

The first and one of the most likely problems is an authentication issue with your database credentials. Open your wp-config.php file and check that all four of the following are defined and correct: DB_NAME (the name of your database), DB_USER (the username of the account accessing the database), DB_PASSWORD (the password for that user) and DB_HOST (usually “localhost”, though some hosts use a different value). A single typo in any one of these four fields is enough to trigger the database connection error, so check them carefully.

Another fairly likely issue is related to that. You added a new database and a new user, and your credentials are correct in the wp-config.php file. What now? Well, check your cPanel database management section - it’s possible that you failed to give the new user permissions to actually access the database. You are going to need to use cPanel to manage new users or new databases and make sure that the users are granted access to the database.

Another issue that’s somewhat related to authentication, but not quite, is an access issue caused by a firewall. In particular, ModSecurity loves to block admins from WordPress because they tend to access it frequently or make unusual requests.

To fix this problem, find your firewall settings and make sure that you’ve whitelisted yourself or your admins - it’s a fairly easy fix. But it’s one of the causes that can be hard to figure out because others see the site working fine.

One more authentication-adjacent fix worth trying: if your server is running low on available PHP memory, WordPress can fail to complete the database handshake. Try adding the following line to your wp-config.php file to raise the PHP memory limit:

define('WP_MEMORY_LIMIT', '256M');

This sets the memory limit to 256M, which is the recommended value and resolves connection errors that are actually memory exhaustion errors in disguise.

Conflict Issues

If your authentication checks out and you can’t find any problems with users or passwords, you should check if any of your plugins were added or updated when this issue started. The same goes for your theme files, which I’m treating as a sort of plugin for the purposes of this section.

Sometimes you can find conflicts with plugins or themes. Since your plugin and theme files are PHP code, sometimes that code can be buggy in a way that works in isolation, but not in conjunction with other plugins or theme files. Incidentally, there’s a bit of overlap here with the next section, on corrupted files; you can use some of the same troubleshooting to fix problems there as well.

Log into your server and find the wp-content folder. In that folder, you should find folders with names like “plugins”, “themes” and “uploads”.

Start by renaming the plugins folder. Just add a simple 1 or _ to the end of the folder, so “plugins” becomes “plugins_”.

Since WordPress is looking for the “plugins” folder, it won’t find it and will assume there are no plugins - it will then work as if you have no plugins installed. Check your site. Does it work? If so, one of your plugins is causing the issue. Otherwise restore the name of the plugins folder and change the name of the themes folder. Does it work now? If so, your theme is the culprit. Otherwise you have other issues and should move on to the next section.

Once you have the issue narrowed down to either plugins or themes, go into the folder and look at individual folders for plugins or themes. Start doing the rename trick and removing individual plugins to test. Keep checking until you find the one that you deactivate that makes your site work.

When testing themes, it’s easier to go into your WordPress admin dashboard and change the theme for your site. Start with the default theme; if it works, your custom theme is the problem. Try reinstalling the theme, or contact your developer to work on it if the theme was custom-made for your site.

Corruption Issues

Finally, we have the file problems. You can have two sources of corruption here: files or databases. Files is a better problem to have.

Go to WordPress.org and download a new copy of WordPress and unzip it locally. Find the wp-admin and wp-includes folders. Also find the other root files except for wp-config.php.

Go to your server and back up all your existing data. You don’t want to do a restore and find you made things worse with no recourse, after all. Once you have the backup, take your new versions of the wp-admin, wp-includes and root files and copy them over. If any of the files were corrupted, WordPress would have stopped working and replacing the files should fix it.

If everything above has failed to work, it’s time to look at the worst case scenario - it’s possible that your MySQL installation, your phpMyAdmin installation, or your database itself is corrupted. You may need to reboot the server - something your web host can help with - or you might need to restore from a backup. Something broke and these kinds of errors are usually unfixable without a full restore. Which is a reminder: always keep backups. Whether you use a plugin like UpdraftPlus, a managed hosting backup system, or a manual schedule, make sure that you have a recent restore point before disaster strikes.