“Error establishing a database connection”: What It Means and How to Fix It

Certain errors can dissolve all but the most hardened WordPress user’s resolve. One of the most potentially problematic is “Error establishing a database connection.” To add salt to the wound, this particular error can be due to one of many potential causes, making diagnosis a real challenge if you’re not sure where to start.

Thankfully, there are a few simple steps you can take to troubleshoot and resolve the “Error establishing a database connection” error. The process itself is foolproof, and you won’t need a degree in Computer Science to follow through; just an FTP connection to your website and a text editor.

In this post, we’ll cover why this error occurs and how to fix it. We’ll include step-by-step instructions and offer advice on what to do if the problem remains unresolved. But before all that, let’s take a look at what the “Error establishing a database connection” actually means.

What Does “Error establishing a database connection” Mean?

“Error establishing a database connection” is an exceptionally common problem. In simple English, it means that your site’s PHP code wasn’t able to connect to its MySQL database to load everything it needs to build the webpage in question. That’s also why you see a blank screen with nothing more than the error message across the top.

In most cases, the cause of this error comes down to one of four common reasons:

1. Incorrect login details. If your site’s database has different login credentials than the admin panel, then your website won’t be able to access the database using the old credentials.
2. Unresponsive database server. At times the problem isn’t on your end. Your database’s server could be down due to a problem on the part of your hosting provider. Another probable related cause may be that your site is experiencing a traffic spike that your server can’t cater to.
3. Corrupted WordPress files. Messing around with your site’s core files can potentially cause an error. This can happen both ways, in terms of both adding corrupt code or removing essential code from a PHP file.
4. Corrupted database. Anything from installing a faulty plugin or theme to external server damage can cause your WordPress database to become corrupted.

With so many plausible reasons causing the error, it’s important to go about troubleshooting the problem systematically.

How Do I Troubleshoot “Error establishing a database connection”?

Our approach to troubleshooting the “Error establishing a database connection” is all about tackling the problem head-on. We’ll start out by trying to figure out the root cause of the problem, and then we’ll systematically begin the troubleshooting process.

Since you’ll be dealing with the WordPress database and core files, it’s always a good (nay, essential!) idea to create a backup of your site before you begin. We recommend going with the UpdraftPlus backup plugin if you’re looking for a free solution. If you’re willing to splash the cash on a premium offering, then VaultPress is an excellent option.

We’ll be using the FileZilla FTP client for troubleshooting “Error establishing a database connection”. If you don’t already have your FTP login credentials handy, you can almost certainly access them from within your hosting dashboard (ask your hosting provider if you’re not sure how to access them).

Step #1: Identify the Problem Area

WordPress comes with built-in functionality that attempts to repair your site’s database. To enable the feature, navigate to your site’s wp-config.php file in the root directory to access the installation and configuration settings.

Open up the wp-config.php file in FileZilla’s default text editor and add the following line of code at the bottom:

define( ‘WP_ALLOW_REPAIR’, true );

Adding this line enables you to repair your site’s database by heading over to http://www.yourwebsite.com/wp-admin/maint/repair.php. Remember to replace www.yourwebsite.com with the URL of your website. Once you visit the link, you’ll see the following screen:

You can select either one of the two options. (Repair and Optimize Database will take a little longer than Repair Database). Once you’re done repairing your WordPress site’s database, remove the line of code from the wp-config.php file. (Doing so ensures that no one else will be able to access your site’s repair page.)

Once you’re done, go to your website to see if the error has been resolved. If that didn’t do the trick, continue to Step #2.

Step #2: Check Your Database Login Credentials

There’s a chance that your database’s login credentials may have stopped working. If you’ve recently switched hosting companies or modified your database’s information then it’s even more likely. This is because the wp-config.php file may not have been updated as necessary.

If you don’t already have the wp-config.php file open from the last step, head over to your site’s root directory from FileZilla once again and open it up in a text editor. You should see the database’s login information near the top of the file:

// ** MySQL settings – You can get this info from your web host ** //
/** The name of the database for WordPress */
define( ‘DB_NAME’, ‘database_name_here’ );

/** MySQL database username */
define( ‘DB_USER’, ‘username_here’ );

/** MySQL database password */
define( ‘DB_PASSWORD’, ‘password_here’ );

/** MySQL hostname */
define( ‘DB_HOST’, ‘localhost’ );

There are four attributes that WordPress needs to access your site’s database:

1. The name of the database for WordPress.
2. The MySQL database username.
3. The MySQL database password.
4. The MySQL hostname.

If the value of any of these attributes is incorrect then WordPress will not be able to establish a connection with the database. You can use PHPMyAdmin by logging into your site’s cPanel dashboard and testing out your existing credentials.

Step #3: Validate Your Database Username and Password

In order to validate your database’s username and password, create a PHP file in your WordPress site’s root directory. You can name it whatever you want. We’ll call ours testdatabase.php.

Now, add the following lines of code into the testdatabase.php file:

<?php
$link = mysql_connect(‘localhost’, ‘root’, ‘password’);
if (!$link) {
die(‘Connection not successful: ‘ . mysql_error());
}
echo ‘Connection was successful!’;
mysql_close($link);
?>

Be sure to replace the variables localhost, root, and password with those specific to your database. You can get the login credentials from the wp-config.php file in Step #2. Once you’re done with that, save the file. Now, head over to http://www.yourwebsite.com/testdatabase.php. If you see the message Connection was successful!, then the login details are correct.

However, if you see an error message starting with Connection not successful: then there’s a problem with your database’s host, username, or password. If that’s the case then move on to Step #4 to see how to create a new database user.

Step #4: Create a New Database User

To create a new database user, login to your WordPress site’s cPanel. Navigate to Databases > MySQL Databases from the dashboard (your interface may vary).

Within the resultant screen, scroll down to the MySQL Users section. Add in the login credentials for the new user and click the Create User button when you’re done:

After you’ve created the new database user, you’ll have to assign it to your site’s database. If you’re not sure what your database’s name is, refer to the wp-config.php file in Step #2 to get the value after attribute DB_NAME.

To assign the new user to your database, scroll down to Add User to a Database section on the same screen. Select the username of the new user and click the Add button. Now, go back to your site’s wp-config.php file and replace the existing database username and password with the new credentials.

Once that’s done, try accessing your WordPress website. If it doesn’t work then chances are your site’s files are corrupted.

Step #5: Fix Corrupted WordPress Files

If nothing else works, then as a last resort, you can try to fix your site’s corrupted WordPress files. And by “fix” we mean “wipe out completely.” Many users who reported this problem found that the issue was resolved once they cleared their files. The process involves replacing the corrupted files with fresh new WordPress files. At this stage it’s obviously especially important to make sure you have a backup of your site on your local drive!

First, download a fresh copy of the WordPress CMS from WordPress.org. Next, unzip the file in your local drive. Delete the entire wp-contents folder and the wp-config.php file. This ensures there’s no chance of overwriting your current wp-config.php file or losing important plugin and theme information. After deleting the corrupted files, paste the rest of the files into your WordPress root folder using FileZilla.

Once you’re done with that, your website should (hopefully) start working.

Conclusion

“Error establishing a database connection” is a pretty common WordPress error. With a little troubleshooting, you can typically fix it on your own in a matter of minutes; the five steps we’ve outlined above should fix your problem in the majority of cases.

However, there can be more esoteric reasons for encountering the error message, and we couldn’t possibly cover every potential cause in this article. If you’ve followed the above steps carefully and are still struggling, your next step is to reach out to your hosting provider to see if they can troubleshoot and resolve the issue on your behalf. Beyond that, it may be necessary to hire professional help, but that’s unlikely to be necessary if you follow the above steps.

Speaking of which, here’s a quick recap of those five steps you need to follow to troubleshoot the error:

1. Identify the problem area.
2. Check your database login credentials.
3. Validate your database username and password.
4. Create a new database user.
5. Fix corrupted WordPress files.

Were you able to determine what caused the “Error establishing a database connection” error on your WordPress site and fix the issue? Let us know in the comments section below!